CLI reference

Captured from fishtea help when this page was built, so it is whatever the shipped binary actually does.

fishtea — describe once, derive everything

  fishtea templates           list the archetypes and their onboarding interviews
  fishtea new <id> --template <archetype> [--dir path] [--name "Name"] [--answers a.json | --interactive]
  fishtea version             framework, spec format, and what this application pins
  fishtea versions            every installed version; * is the one running
  fishtea use <version>       switch to another installed version (and back — it is one symlink)
  fishtea upgrade [--from <checkout>]
                              install a newer framework beside the current one and switch to it
  fishtea uninstall <version> remove an installed version that is not current
  fishtea update [--dry-run]  bring this application up to the framework without regenerating it
                              [--adopt] start tracking an application made before provenance existed
  fishtea plugin list|info|add|remove|create|promote
                              everything outside the conversation: integrations, design systems, auth
  fishtea ui-assets           regenerate the browser bundle's design-system stylesheet
  fishtea validate            validate spec.json and print section hashes
  fishtea doctor              check the spec, the database, the classifier and the binding
  fishtea derive [--ddl|--tools|--forms]
  fishtea migrate [--allow-destructive]
  fishtea seed                load seed/*.json
  fishtea serve [--host 0.0.0.0] [--port 3000] [--intent lexical|needle] [--strict]
  fishtea headless [--script scripts/walkthrough.json] [--json]
  fishtea tui                 operator console: onboard, edit, run
  fishtea up [--detach]       build and start the stack (ctrl-c stops it)
  fishtea down [-v]           stop and remove it; -v also deletes the data volume
  fishtea stop | start        pause and resume without removing anything
  fishtea ps | logs [service] what is running, and follow its output
  fishtea restart [service]   default: core
  fishtea bench               performance harness against a running stack
  fishtea notify <visitorId> "<text>"

  --app <dir>        application directory (default FISHTEA_APP or cwd)
  --db <url>         Postgres, overriding DATABASE_URL
  --classifier <url> needle pool, overriding CLASSIFIER_URL
  --host / --port    what the core binds (default 0.0.0.0:3000, reachable from other machines)
  --workspace <dir>  where "new" puts applications (default FISHTEA_WORKSPACE, else beside fishtea)

  env: DATABASE_URL, CLASSIFIER_URL, FISHTEA_HOST, FISHTEA_PUBLIC_HOST, PORT, FISHTEA_INTENT,
       FISHTEA_STRICT, FISHTEA_OPERATOR_TOKEN, FISHTEA_WORKSPACE, FISHTEA_APP, FISHTEA_HOME

Where commands run

Every command takes --app <dir>, defaulting to FISHTEA_APP and then to the current directory if it has a spec.json. A generated application wraps these in its own package.json scripts, so bun run dev and fishtea serve are the same thing.