CLI · v3.3.0

Command Reference

Every command, flag, argument, env var, and exit behavior. turkeycode and turkey are the same executable.

	Detail
Version	`turkeycode --version`
Help	`turkeycode <command> --help`
Config load	Loads `deploy/.env` on startup, then process env vars.

Command map

Command	Purpose
`run`	Run the full orchestration loop.
`scope`	Interactively converge on a spec without building.
`resume`	Resume from the last checkpoint.
`status`	Show current orchestration status.
`reset`	Reset / nuke orchestration state.
`gate`	Manually check a specific pipeline gate.
`login`	Authenticate with turkeycode.ai.
`run-local`	Run the current project locally in Docker.
`deploy`	Package and deploy to turkeycode.ai.
`deliver`	Deliver a non-web project to GitHub.
`apps`	Manage deployed apps (list/status/logs/delete).
`story`	Bug/story mode: prompt → pointed Jira ticket → run.
`run-ticket`	Run a single existing Jira ticket.
`my-tickets`	List Jira tickets assigned to you, then run one.

run

Run the full orchestration loop. A bare description auto-enters the interactive scope loop first on a TTY; skip it with --spec (or by running non-interactively).

$ turkeycode run <description> [options]

Flag	Description
`-j, --jira <project>`	Jira project key — create Jira tickets per phase.
`-g, --github <repo>`	GitHub repo (owner/repo) — create PRs per phase.
`-s, --spec <file>`	Spec file path. Skips the scope loop (fully autonomous).
`--persona <file>`	Persona the scope agent embodies.
`-v, --verbose`	Verbose output.
`-w, --allow-warnings`	Allow warnings in QA (only blockers must be zero).
`--no-push`	Skip git push (local-only / no_push remotes).
`--no-pr`	Skip gh pr create (implied by --no-push).
`--aar`	Generate a per-phase After-Action Report (off by default).
`--strict-phases`	Gate every phase on zero warnings; disables the polish pass.
`--type <type>`	Force project type, skipping auto-detection (see below).
`--base <branch>`	Base branch override. Defaults to detected main/master.
`--feature <branch>`	Feature branch — phases branch off and merge back into it.

--type accepts: web-fullstack, web-frontend, web-api, cli, library, desktop, mobile, embedded, legacy, monorepo.

# Converge interactively, then build straight through
$ turkeycode run "a habit tracker with streaks and reminders"
 
# Fully autonomous from a spec
$ turkeycode run "Build a project management tool" --spec spec.md
 
# Per-phase PRs to GitHub, let cosmetic warnings pass
$ turkeycode run "SaaS dashboard with Stripe billing" --github me/dash -w
 
# Force a CLI build into a gitflow repo
$ turkeycode run "docker-monitoring CLI" --type cli --feature develop

Scope auto-skip

The interactive loop is skipped when you pass --spec, point at a spec file, or run non-interactively (CI / piped stdin).

scope

Interactively scope a build into a spec (reflect-and-correct loop) without building. Writes the working model and confirmed spec under .turkey/.

$ turkeycode scope <description> [options]

Flag	Description
`-s, --spec <file>`	Seed spec/notes file to start the working model from.
`--persona <file>`	Persona the scope agent embodies.
`--model <model>`	Override the model used for the scoping agent.
`-v, --verbose`	Stream the underlying session output.

resume

Resume orchestration from the current state in .turkey/state.json.

$ turkeycode resume [options]

Flag	Description
`-v, --verbose`	Verbose output.
`-w, --allow-warnings`	Allow warnings in QA (only blockers must be zero).
`--aar`	Generate a per-phase After-Action Report.
`--strict-phases`	Gate every phase on zero warnings (disables the polish pass).
`--no-push`	Skip git push.
`--no-pr`	Skip gh pr create (implied by --no-push).
`--base <branch>`	Base branch override (seed/override; persisted to state).
`--feature <branch>`	Feature branch (seed/override; persisted to state).

status

Show the current orchestration status (phase, QA attempts, gate progress).

$ turkeycode status

reset

Reset orchestration state — wipes the .turkey/ state directory.

$ turkeycode reset [-f|--force]

Flag	Description
`-f, --force`	Force reset without confirmation.

gate

Manually check a specific pipeline gate (useful for debugging a stalled build).

$ turkeycode gate <gate> [options]

Arg / Flag	Description
`<gate>`	scope · research · plan · phase-build · qa-smoke · qa-functional · qa-visual · qa-verdict · code-review · aar
`-p, --phase <number>`	Phase number for phase-specific gates (default 1).
`-a, --attempt <number>`	Attempt number for QA gates (default 1).

Gate artifacts & validation

Gate	Artifact	Passes when
scope	`reference/scope.done`	starts with DONE, specs.md > 200 chars
research	`reference/research.done`	exists, specs.md > 200 chars
plan	`phase-plan.json`	valid JSON, 2–5 phases
build	`phases/phase-N.done`	exists
qa-smoke	`qa/phase-N/smoke-M.done`	exists
qa-functional	`qa/phase-N/functional-M.done`	exists
qa-visual	`qa/phase-N/visual-M.done`	exists
qa-verdict	`qa/phase-N/verdict-M.json`	0 blockers
code-review	`reviews/phase-N.md`	exists
aar	`aar/phase-N.done`	exists

Authenticate with turkeycode.ai. Stores credentials at ~/.turkeycode/credentials.json. API base is https://turkeycode.ai/api/v1.

$ turkeycode login [-t|--token <api-key>]

Flag	Description
`-t, --token <api-key>`	API token for headless / CI login (else prompts to paste).

Get or rotate your key at turkeycode.ai/settings/api-keys.

run-local

Run the current project locally in Docker — mirrors turkeycode.ai hosting. Auto-detects app name, stack, and tier.

$ turkeycode run-local [-p|--port <port>]

Flag	Description
`-p, --port <port>`	Local port to expose (default 3000).

deploy

Package and deploy the current project to turkeycode.ai. Requires login first. Auto-detects your stack and generates a Dockerfile if none exists (an existing one is used as-is).

$ turkeycode deploy [options]

Flag	Description
`-n, --name <subdomain>`	Custom subdomain name.
`-d, --domain <domain>`	Custom domain (Pro+).
`-t, --tier <tier>`	Explicit tier: free \| starter \| pro \| business.
`-e, --env <file>`	Env file to inject (e.g. .env.production).
`--skip-build`	Skip the build step.

Hosting tiers

Tier	Price	What you get
Free	$0/mo	Static hosting, subdomain, sleeps on idle
Starter	$12/mo	Full stack (DB + Redis), always-on
Pro	$29/mo	+ Stripe, Auth, S3, Email, background jobs, custom domain
Business	$49/mo	+ Priority support, daily backups, analytics

$ turkeycode deploy                       # -> https://my-app.turkeycode.ai
$ turkeycode deploy --tier starter
$ turkeycode deploy --name cool-app
$ turkeycode deploy --env .env.production

deliver

Deliver a non-web project (CLI, library, desktop, mobile) to your GitHub instead of hosting it. Uses your existing gh auth — no extra tokens. Go projects are cross-compiled (Linux/macOS/Windows), Rust gets a native release build, and a GitHub release is created with binaries attached.

$ turkeycode deliver [options]

Flag	Description
`-n, --name <name>`	Repository name.
`-d, --description <desc>`	Repository description.
`--public`	Create a public repo (default: private).

apps

Manage deployed apps. list is the default subcommand.

$ turkeycode apps [list]
$ turkeycode apps status [app-name]
$ turkeycode apps logs <app-name> [-n|--lines <number>]
$ turkeycode apps delete <app-name> [-f|--force]

Subcommand	Description	Options
`list`	List all deployed apps (default).	—
`status [app-name]`	Show app health and status.	—
`logs <app-name>`	Tail logs for an app.	`-n, --lines`
`delete <app-name>`	Tear down a deployed app.	`-f, --force`

Tickets (Jira)

These commands require Jira env vars: JIRA_HOST, JIRA_EMAIL, JIRA_TOKEN (and JIRA_PROJECT for story, since it creates tickets). Generate a token at id.atlassian.com.

story

Bug/story mode: turn a prompt into a points-estimated Jira ticket (auto bug-vs-story), burn down its epic, then run it.

$ turkeycode story <prompt> [options]

Flag	Description
`-e, --epic <key>`	Parent epic key. Omit for an interactive picker; supplying it links + reports burndown.
`--bug`	Force issue type Bug.
`--story`	Force issue type Story.
`--points <n>`	Override the estimated story points.
`--budget <n>`	Override the epic point budget used for burndown.
`--dry-run`	Estimate only. Create nothing, run nothing.
`--no-run`	Create + point the ticket, but skip the run flow.
`--triage-only`	Create the ticket, then stop after triage.
`-v, --verbose`	Verbose output.
`--manifest <path>`	Override the repos.yaml manifest path.
`--mcp-config <path>`	Override MCP config path (else TURKEYCODE_MCP_CONFIG).

Epic burndown is read-and-report (remaining = epic budget − committed points); it never writes back to the epic, so it never fights Jira's native rollup.

$ turkeycode story "users can export their dashboard to CSV"
$ turkeycode story "fix broken CSV export on empty sets" --epic PROJ-100 --bug
$ turkeycode story "add SSO via Okta" --dry-run
$ turkeycode story "rate-limit the public API" --no-run

run-ticket

Run a single existing Jira ticket: triage it, then research (non-coding) or build + push branches (coding).

$ turkeycode run-ticket <key> [options]

Flag	Description
`-v, --verbose`	Verbose output.
`--manifest <path>`	Override the repos.yaml manifest path.
`--mcp-config <path>`	Override MCP config path (else TURKEYCODE_MCP_CONFIG).
`--triage-only`	Stop after triage. No branches, build, or Jira comment/worklog.

my-tickets

List Jira tickets assigned to you, then pick one to run.

$ turkeycode my-tickets [options]

Flag	Description
`-v, --verbose`	Verbose output.
`--include-done`	Include tickets in the Done status category.
`-k, --key <key>`	Skip the picker and run the given key directly.
`--manifest <path>`	Override the repos.yaml manifest path.
`--mcp-config <path>`	Override MCP config path (else TURKEYCODE_MCP_CONFIG).
`--triage-only`	Stop after triage. No branches, build, or Jira comment/worklog.

Environment variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	No*	Anthropic API key. *Not needed with Claude Max/Pro via claude login.
`ANTHROPIC_AUTH_TOKEN`	No	Alternative auth token honored by the direct API client.
`GH_TOKEN`	No	GitHub token (alternative to gh auth login).
`JIRA_HOST`	No	Jira instance hostname (e.g. company.atlassian.net).
`JIRA_EMAIL`	No	Jira account email.
`JIRA_TOKEN`	No	Jira API token.
`JIRA_PROJECT`	No	Jira project key. Required for story (it creates tickets).
`TURKEYCODE_MCP_CONFIG`	No	Default MCP config path for ticket commands.

Files, state & paths

Path	What
`.turkey/`	Per-project build state (gitignored).
`.turkey/state.json`	Current phase, QA attempts.
`.turkey/audit.log`	Timestamped event log.
`.turkey/fatal.log`	Why a long autonomous run died (survives buffered stdout).
`.turkey/reference/specs.md`	Confirmed intent spec + research survey.
`.turkey/phase-plan.json`	The 2–5 phase plan.
`.turkey/qa/phase-N/`	Smoke / functional / visual reports + verdict.
`.turkey/reviews/`	Code review reports.
`~/.turkeycode/credentials.json`	turkeycode.ai login credentials.
`~/.turkeycode/persona.md`	Global scoping persona (lowest-priority source).
`deploy/.env`	Env file auto-loaded by the CLI on startup.

Exit & failure behavior

Command handlers exit non-zero on failure (failed auth, invalid ticket selection, deploy/detection errors), printing an ❌-prefixed message. Uncaught exceptions and unhandled rejections are logged to .turkey/fatal.log and exit 1 — check that file when a background run dies silently. Most builds are resumable: after a crash, turkeycode resume continues from the last gate that passed.

Tracks turkeycode v3.3.0. If the CLI's command surface changes, update this page from the upstream src/index.ts and README.md.