Reference
CLI.
The command is t25, with factory retained as an alias during the
name migration. From the repository, invoke with npm run t25 -- <command> —
the -- passes arguments to the program instead of npm.
The cycle of a task
# open a task
npm run t25 -- create "Add metrics endpoint" \
--body "Expose latency by route" --type feature --risk medium
# read the brief, then release it
npm run t25 -- spec TASK-0001
npm run t25 -- spec-approve TASK-0001
# the go/no-go gate
npm run t25 -- approve TASK-0001
# monitor and correct course
npm run t25 -- list
npm run t25 -- retry TASK-0001
npm run t25 -- cancel TASK-0001
spec-approve and approve are different gates:
the first releases the brief into a plan; the second is the plan go/no-go. Neither one
merges — that remains your decision, through the cockpit or t25 merge.
Environment and diagnostics
| Command | What it does |
|---|---|
t25 doctor |
JSON pre-flight report — bind authentication, Docker, PostgreSQL client, state_dir and web/dist. Exits with an error when a check is error. Check here first when something will not start. |
t25 snapshot |
Read-only JSON manifest of state-directory files: relative path, bytes and SHA-256. |
t25 list |
The tasks and their current states. |
Task worktree
npm run t25 -- workspace TASK-0001 # where the worktree is npm run t25 -- cleanup TASK-0001 # remove the worktree
cleanup refuses removal when there are uncommitted changes and never forces it.
If it complained, inspect the tree before trying again — there is usually real work inside.
Multiple projects
npm run t25 -- projects
npm run t25 -- create "Title" --project other-service
Workers
Distributed execution: the control plane issues leases and each host runs a worker that
claims them. The credential lives only in an environment variable
(FACTORY_WORKER_CREDENTIAL, with the initial bootstrap in
FACTORY_WORKER_BOOTSTRAP) — never in t25.yaml.
npm run t25 -- worker-bootstrap --project default npm run t25 -- worker run --control-plane-url https://localhost:8443 --worker-id worker-a npm run t25 -- worker-approve worker-a npm run t25 -- workers
The two-host, TLS and lease-reclaim runbook is in GO-LIVE.md.
MCP: your agent operating the factory
npm run t25 -- api-key create --label "my-agent" --role viewer --read-only export T25_MCP_API_KEY=<secret printed above> export T25_MCP_SCOPE=read npm run mcp # stdio: point your agent MCP config at this command
The catalog has 52 tools in four cumulative layers, filtered by
T25_MCP_SCOPE (default read): 21 read tools, 30 in
operate, 38 in approve and 52 in admin.
The key remains the authority; the scope only hides tools from the stdio process.
operate covers pause/resume/cancel/retry, briefs and answers.
approve adds task creation, spec, the plan gate, merge and rollback.
admin covers the fleet, API keys, triggers, users and policies.
The worker protocol, shell, secrets and direct Postgres access stay out.
What MCP does not replace. Spec and merge remain capability gates
in the API. Without the approver/admin role, a tool
may appear in the broad catalog but the API rejects it. The worker protocol
(HMAC, lease, heartbeat) does not pass through MCP.
Review an existing PR
npm run t25 -- review-pr 42 npm run t25 -- review-pr 42 --comment
Reviews; it does not implement or merge.
Repository verification
npm run typecheck npm test npm run web:build
These are the three commands T25 considers "ready" for backend work — and
web:build also verifies that the cockpit still compiles.