Getting Started

1. Prerequisites

Optional, unlocked later: the GitHub CLI (gh auth login) for pushing builds and turkey deliver; and Jira env vars for story, run-ticket, and my-tickets.

Pick how the model is powered

Option A — Claude Max / Pro (recommended, no API key):

$ npm install -g @anthropic-ai/claude-code
$ claude login
# TurkeyCode now uses your Claude CLI session automatically.

Option B — API key:

$ export ANTHROPIC_API_KEY=sk-ant-your-key-here

2. Install the CLI

# Zero-install, one-off
$ npx turkeycode run "your app description"
 
# Or install globally (gives you both turkeycode and the turkey alias)
$ npm install -g turkeycode

Verify:

$ turkeycode --version    # -> 3.3.0
$ turkey --help           # turkey is an alias for turkeycode

3. Your first build

The prompt is the hard part — so run converges with you first when you're at a terminal. It restates what it thinks you want, then hands you the next decision as a short list of options. You ratify by typing a number. It leans toward the smaller cut and won't bury you in questions.

$ mkdir bookmark-app && cd bookmark-app
 
$ turkeycode run "Build a bookmark manager with tags, search, \
  and a Chrome extension. Stack: Next.js, Tailwind, SQLite."

What happens, in order:

Skip the scope loop (go fully autonomous)

$ turkeycode run "Build a project management tool" --spec spec.md

The loop is also auto-skipped whenever input is piped or there's no TTY — automation never blocks waiting for a number.

Scope without building

$ turkeycode scope "a habit tracker with streaks and reminders"
# writes .turkey/reference/specs.md — then later:
$ turkeycode resume

Make it scope like you

Drop a persona.md — your operating manual for how you scope, what you cut, your defaults — and the scope agent embodies it, generating the options you'd weigh in your voice.

$ turkeycode run "internal admin tool" --persona persona.md

Load order (first found wins): --persona <file> → ./.turkey/persona.md → ~/.turkeycode/persona.md → a built-in scoping doctrine.

4. Run it in the background (long builds)

$ cd /path/to/project
$ setsid nohup turkeycode run "your description" --verbose \
  > build.log 2>&1 < /dev/null &

Monitor:

$ tail -f build.log           # live log
$ turkeycode status           # structured status
$ ps aux | grep turkeycode    # confirm it's alive

5. When things go sideways

A killed run leaves a record at .turkey/fatal.log, and you can almost always pick up where you left off with turkeycode resume.

6. Ship it

Web apps → host on turkeycode.ai

# Authenticate once (stores creds at ~/.turkeycode/credentials.json)
$ turkey login
 
# Deploy the current project
$ turkey deploy
# -> Live at https://my-app.turkeycode.ai

Pick a tier, subdomain, or inject env:

$ turkey deploy --tier starter
$ turkey deploy --name cool-app
$ turkey deploy --env .env.production

Manage what you've shipped:

$ turkey apps                    # list deployed apps
$ turkey apps status my-app      # health + status
$ turkey apps logs my-app        # tail logs
$ turkey apps delete my-app      # tear down

Non-web (CLI, library, desktop, mobile) → deliver to GitHub

$ turkey deliver                 # push to your GitHub (private by default)
$ turkey deliver --public        # public repo
$ turkey deliver --name my-cli   # custom repo name

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 the binaries attached.

Try it locally first

$ turkey run-local            # serves on :3000
$ turkey run-local --port 8080

7. Iterate with tickets (optional, Jira)

With Jira configured (JIRA_HOST, JIRA_EMAIL, JIRA_TOKEN, and JIRA_PROJECT for story):

# Describe it -> TurkeyCode files its own pointed ticket, burns down the epic, runs it
$ turkeycode story "users can export their dashboard to CSV"
 
# Run a ticket that already exists
$ turkeycode run-ticket PROJ-123
 
# Pick from tickets assigned to you
$ turkeycode my-tickets

See the Command Reference → Tickets for the full flag set and the bug-vs-story estimation flow.

Where state lives

Everything the orchestrator tracks is under .turkey/ in your project (gitignored):

.turkey/
  state.json              current phase, QA attempts
  audit.log               timestamped event log
  fatal.log               why a run died (if it did)
  reference/specs.md      confirmed spec + research survey
  phase-plan.json         the 2-5 phase plan
  phases/phase-N.done     build completion gates
  qa/phase-N/             smoke/functional/visual reports + verdict
  reviews/                code review reports
  screenshots/            visual QA captures

turkeycode status reads this; turkeycode resume continues from it; turkeycode reset --force wipes it.