CLI

Example Walkthrough

One prompt to a deployed app. We'll build BookmarkBird, a bookmark manager with tags and search, then ship it to turkeycode.ai. The terminal frames below mirror what you actually see.

Following along?

You need Node 18+, Git, and Claude Code authenticated (claude login). See Getting Started for setup.

1. Kick it off

Make an empty directory and hand run a one-line description. On a terminal it converges with you before writing any code.

bookmark-bird -- zsh
$ mkdir bookmark-bird && cd bookmark-bird
 
$ npx turkeycode run "A bookmark manager with tags, full-text \
  search, and a Chrome extension. Stack: Next.js, Tailwind, SQLite."
 
============================================================
TURKEYCODE - PHASE-BASED ORCHESTRATION
============================================================
Initialized project: A bookmark manager with tags...
Persona: built-in scoping doctrine (default). Drop ~/.turkeycode/persona.md to make it yours.

2. Scope (converge first)

It restates what it thinks you want, then hands you the next decision as a short list. You ratify by typing a number. It leans toward the smaller cut.

bookmark-bird -- zsh
────────────────────────────────────────────────────────────
🎯 Here's what I think you want:
   A personal bookmark manager. Save a URL, tag it, and find
   it again with full-text search across title + notes. A
   Chrome extension saves the current tab in one click.
 
   Decision 1 of 3 - Accounts?
    1. Single-user, local (no auth)        ← leaning
    2. Multi-user with email login
────────────────────────────────────────────────────────────
> 1
 
   Decision 2 of 3 - Search backend?
    1. SQLite FTS5 (built in, fast)        ← leaning
    2. Add a separate search service
> 1
 
   Decision 3 of 3 - Extension scope (v1)?
    1. Save current tab only               ← leaning
    2. Save + organize from a popup
> 1
 
✅ Scope locked. Writing .turkey/reference/specs.md

Skip the loop

Pass --spec spec.md (or run non-interactively in CI) and it goes straight to building, no questions asked.

3. Research and plan

With scope locked it surveys the stack and prior art, then breaks the work into 2-5 phases with concrete deliverables.

bookmark-bird -- zsh
=== PHASE: RESEARCH ===
Surveying stack, architecture, prior art...
✓ research.done - specs.md updated with the survey
 
=== PHASE: PLAN ===
📋 Plan: 3 phases
   Phase 1 - Core: schema, save/list/delete, SQLite FTS5 search
   Phase 2 - Tagging: tags, filter-by-tag, tag management UI
   Phase 3 - Chrome extension: one-click save of the active tab
✓ phase-plan.json - valid (3 phases)

4. Build and QA, one phase at a time

Each phase is one focused build session, then a gauntlet: a fast smoke check, then smoke -> functional -> visual QA. Blockers must hit zero. Up to 5 retry cycles per phase.

bookmark-bird -- zsh
BUILD PHASE 1: Core
--- Building Phase 1: Core ---
 
=== QUICK SMOKE CHECK (pre-QA) ===
Running fast validation before expensive QA...
✓ deps installed · ✓ compiles · ✓ dev server boots
=== QUICK SMOKE CHECK PASSED ===
 
--- Tier 1: Smoke Test ---
Smoke passed in 41s - proceeding to functional + visual tests
--- Tier 2+3: Functional + Visual (PARALLEL) ---
--- Generating Verdict ---
QA PASSED - verdict is CLEAN
Phase 1 built in 7m 12s
📝 Code review: reviews/phase-1.md
✅ Merged phase-1 into main

Phases 2 and 3 run the same loop. A phase that fails QA loops on the same report so fixes are verified, not re-litigated.

bookmark-bird -- zsh
BUILD PHASE 2: Tagging
QA FAILED - 2 blockers (tag filter returns empty on multi-tag)
🔧 Fix attempt 1 - all issues in one session, full context
QA PASSED - verdict is CLEAN
✅ Merged phase-2 into main
 
BUILD PHASE 3: Chrome extension
QA PASSED - verdict is CLEAN
✅ Merged phase-3 into main

5. Dinner is served

bookmark-bird -- zsh
============================================================
ORCHESTRATION COMPLETE
============================================================
🦃 Your project is ready! Here's what you can do next:
 
  Run it locally:
    turkey run-local
 
  Deploy to turkeycode.ai:
    turkeycode deploy

6. Ship it

Authenticate once, then deploy. The CLI auto-detects the stack, generates a Dockerfile if you don't have one, packages the app, and serves it.

bookmark-bird -- zsh
$ turkey login
✅ Logged in as you@example.com
 
$ turkey deploy
 
╔══════════════════════════════════════════════════════════╗
║                  TURKEY DEPLOY                            ║
╚══════════════════════════════════════════════════════════╝
 
Authenticated as you@example.com
 
Detecting project...
  App:    bookmark-bird
  Stack:  Next.js + SQLite
  Tier:   starter -- needs a database, always-on
 
Building image... done
Uploading... done
✅ Live at https://bookmark-bird.turkeycode.ai

7. Manage what you shipped

bookmark-bird -- zsh
$ turkey apps
 
  NAME           STACK             TIER      STATUS         URL
  -------------------------------------------------------------------------
  bookmark-bird  Next.js + SQLite  starter   ✅ running     https://bookmark-bird.turkeycode.ai
 
$ turkey apps logs bookmark-bird --lines 5
  [12:04:01] GET /  200  18ms
  [12:04:01] GET /api/bookmarks  200  6ms
  [12:04:09] POST /api/bookmarks  201  11ms
← Getting StartedFull Command Reference →