CLI commands

The CLI is one binary (skillet_agent, or npx tsx ./src/cli.ts <subcommand> in dev). Run any subcommand directly or through the bundled npm scripts.

Quick reference

Subcommand	Purpose
`chat`	Interactive REPL with the agent.
`run <task>`	One-shot task; exits after the agent replies.
`list`	List the skilletId of every bundled and user crew that `-c` can resolve by id.
`eval_run`	Run an eval suite against an agent.
`eval_grade`	Grade eval results with an LLM judge.
`schema_generate`	Emit the JSON Schema for `.skilled_crew.yaml`.
`schema_check`	Verify the committed schema is in sync with the Zod source.
`log stream`	Print and then follow the JSONL session logs.

The durable job lane (create, list, cost, dispatcher, schedules) is no longer part of this CLI — it moved to the separate skilled_workflow package and its own skilled_workflow binary. See Jobs & Scheduling › CLI reference.

Shared flags

chat and run accept the same set of flags:

Flag	Required	Default	Purpose
`-c, --skilled-crew-yaml-config-path <pathOrId>`	no	`todo_list`	Either a path to a `.skilled_crew.yaml` file or the `skilletId` of a bundled/user crew (see `list`). An existing file wins; otherwise the value is matched against discoverable crew ids.
`-v, --verbose-level`	no	`0`	Repeatable. Each `-v` increases verbosity. `-vv` shows tool calls; `-vvv` shows raw step events.
`-s, --stream`	no	`false`	Stream tokens as they arrive instead of waiting for the full response.
`--user-email <email>`	no	`john@example.com`	The user whose session store, JSONL log, and cost bucket this run is scoped to. The email is the userId (one identity shared with the web client) and must already exist in the user store; the default user is seeded automatically.
`--session-name <name>`	no	`session_<ISO timestamp>_<random>`	Scopes a single conversation within a user. Repeated runs with the same `--session-name` continue the same context.

`chat`


npx tsx ./src/cli.ts chat -c ./data/skillets/todo_list.skilled_crew.yaml
npx tsx ./src/cli.ts chat -c todo_list   # same crew, resolved by skilletId
npx tsx ./src/cli.ts chat                # no -c → defaults to the todo_list crew

Starts a readline REPL. The prompt shows the skillet name. Existing session history is replayed before the first prompt so you can see prior context.

Type a message to send it to the agent.
Type a / command — built-in (slash commands reference) or user-defined (.command.md) — for slash behavior.
Hit Ctrl+C or type /exit to quit. MCP connections are closed cleanly on exit.

`run`


npx tsx ./src/cli.ts run -c ./data/skillets/todo_list.skilled_crew.yaml 'what are my tasks?'

Sends one task, prints the response, exits. Useful for scripting, cron jobs, or quick smoke tests. Same flags as chat. Streaming works (-s).

`list`


npx tsx ./src/cli.ts list

Prints the skilletId and resolved path of every crew that -c can load by id — one per line, id<TAB>path. Crews are discovered from the package’s bundled data/skillets and from your user config directory; a user crew overrides a bundled crew that shares the same id. Use this to find the id to pass to chat -c <id> or run -c <id>.

`eval_run`


npx tsx ./src/cli.ts eval_run \
  -c ./data/skillets/bluesky_social_manager.skilled_crew.yaml \
  -f ./data/skillets/evals/bluesky_evals

Runs every eval in <eval-folder>/evals.json against the skillet. Writes one eval_<id>_run.json per eval into the sibling <eval-folder>_output/ directory. See Evaluations.

Flag	Required	Purpose
`-c, --skilled-crew-yaml-config-path <path>`	yes	The skillet to evaluate.
`-f, --eval-folder-path <path>`	yes	Folder containing `evals.json`; results go to the sibling `<folder>_output/`.
`-v, --verbose-level`	no	Same semantics as for `chat` / `run`.

`eval_grade`


npx tsx ./src/cli.ts eval_grade -f ./data/skillets/evals/bluesky_evals

Reads the eval_<id>_run.json files from a prior eval_run and grades each eval with an LLM judge (default openai/gpt-4.1-nano, overridable with SKILLET_MODEL_EVAL in <provider>/<model> form). Writes eval_<id>_grade.json back into the same <eval-folder>_output/ directory. Scores run 0–10.

Flag	Required	Purpose
`-f, --eval-folder-path <path>`	yes	Folder containing the eval suite and its `evals_output/`.

`schema_generate`


npx tsx ./src/cli.ts schema_generate

Serializes the Zod source to JSON Schema: SkilledCrewYamlConfigZod → data/schemas/skilled_crew.schema.json. Re-run when you change the Zod source. (The .job_workflow.yaml schema is generated by the separate skilled_workflow package’s own schema:generate.) See JSON Schema (VSCode).

`schema_check`


npx tsx ./src/cli.ts schema_check

Regenerates the schema in-memory and compares it to the committed file. Exits non-zero if it differs. This is wired into CI (npm run schema:check) so a stale schema can’t slip in.

`log stream`


npx tsx ./src/cli.ts log stream

Discovers every .jsonl session log under the session-logs root (.skilled-agent/state/.agent_session_logs in a checkout; override with --logs-dir <path>), prints the existing user/agent turns oldest-first, then follows new appends — across all sessions, including running job workers. See Sessions and logs.

Jobs (separate package)

The durable job lane — creating jobs from workflows, listing the board, rolling up cost, running the dispatcher, and managing recurring schedules — is not part of the _skillet_agent CLI. It moved to the separate skilled_workflow package, which embeds the agent runtime as a library and exposes its own skilled_workflow binary (the jobs … command group). The full command tree is documented in Jobs & Scheduling › CLI reference.

npm script shortcuts

The package ships a few common invocations as npm scripts:


npm run dev:chat:todo_list                 # chat with todo_list skillet
npm run dev:run:todo_list                  # one-shot: "what are my tasks?"
npm run dev:chat:bluesky_social_manager    # chat with the bluesky skillet
npm run dev:chat:business_analyst
npm run dev:chat:web_browser
npm run dev:chat:multi_bluesky_agent       # multi-agent example
 
npm run schema:generate                    # schema_generate
npm run schema:check                       # schema_check
 
npm run dev:eval:run:bluesky               # eval_run on the bluesky suite
npm run dev:eval:grade:bluesky             # eval_grade on the bluesky suite
 
npm run dev:log:stream                     # log stream
 
npm run dev:cost:list                      # one-shot cost UI (openai-cost)
npm run dev:cost:list:watch                # live cost UI, refreshed continuously
npm run dev:cost:clear                     # reset the cost tracker

These are aliases — read packages/_skillet_agent/package.json to see what each one maps to. The dev:jobs:* scripts now live in the separate skilled_workflow package.