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 account reset <email>  a visitor's lost password: remove it and end their sessions
  fishtea ui-assets           regenerate the ui bundle's assets from ui/shell plugins (--typecheck: check their code)
  fishtea validate            validate spec.json and print section hashes
  fishtea visitors prune      visitors only tooling produced (headless, present, tests); --yes deletes them
  fishtea present [shape…]    how each answer is laid out (rules.present, or derived); --live asks a running core
  fishtea doctor              check the spec, the database, the classifier and the binding
  fishtea tune data [--trail] [--per-shape 4]
                              derive a training corpus for this application's own classifier
  fishtea tune status         is the corpus, and any installed model, still about this spec?
  fishtea tune install <model.cact> [--as name.cact]
                              put a model trained elsewhere where the pool will find it
  fishtea eval [--check] [--intent lexical|needle] [--versus] [--save --label "..."]
                              run the labelled set: accuracy by population, the floor it implies,
                              and the delta against eval/baseline.json
  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>"
  fishtea admin reset [--username admin]
                              a lost /admin password: back to the first one, changed at next sign-in

  --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.