twin-pilot-cli

0.2.50 verified Fri May 01 auth: no javascript

twin-pilot-cli v0.2.50 is a CLI tool for running AI-powered software factory pipelines from the terminal. It acts as a thin HTTP client that dispatches commands to the Twin Pilot Command Center for project creation, pipeline scheduling, and human-gate approvals. Pipeline execution is handled by Trigger.dev cloud or a local worker for filesystem access. Requires Node.js 20+. Key differentiators: supports local worker execution for agent tasks that need local filesystem access; CI mode with environment variables; human-gate approval workflow. Alternative to other AI coding agents but focused on structured pipeline orchestration.

Common errors

error Error: Cannot find module 'twin-pilot-cli' ↓

cause twin-pilot-cli is not installed.

fix

Run 'npm install -g twin-pilot-cli'.

error twin-pilot: command not found ↓

cause Global install not in PATH.

fix

Run 'npm install -g twin-pilot-cli' and ensure npm global bin is in PATH.

error Authorization failed: API key missing ↓

cause TWINPILOT_API_KEY not set in non-interactive mode.

fix

Set TWINPILOT_API_KEY environment variable or run 'twin-pilot login'.

Warnings

gotcha Requires Node.js 20+ (engines field). Older Node.js versions will fail. ↓

fix Update Node.js to v20 or later.

gotcha CLI is a thin client; most logic runs server-side. If Command Center is down, CLI commands fail. ↓

fix Check TWINPILOT_COMMAND_CENTER_URL and network connectivity.

gotcha API key must be factory-scoped; a leaked key can only operate within that factory, but still a security risk. ↓

fix Rotate keys if leaked, use environment variables in CI.

gotcha The 'twin-pilot' binary is used instead of 'twin-pilot-cli'. ↓

fix Use 'twin-pilot' not 'twin-pilot-cli' in terminal.

Install

npm install twin-pilot-cli

yarn add twin-pilot-cli

pnpm add twin-pilot-cli

Imports

CLI
wrong
```
import twinPilot from 'twin-pilot-cli'
```
correct
```
npx twin-pilot-cli <command>
```
twin-pilot-cli is a command-line tool, not a library. Use npx or global install.
login
wrong
```
npm run twin-pilot login
```
correct
```
twin-pilot login
```
Direct command, not via npm scripts.

API_KEY

wrong

twin-pilot --api-key sk_live_... from-scratch "..."

correct

TWINPILOT_API_KEY=sk_live_... twin-pilot from-scratch "..."

Use environment variable, not CLI flag.

Quickstart

Install, authenticate, create a project, and manage human gates. Also shows CI mode with environment variables.

# Install globally
npm install -g twin-pilot-cli

# Authenticate (opens browser)
twin-pilot login

# Create a new project from a market signal
twin-pilot from-scratch "Meal planning app for busy parents"

# Check status
twin-pilot status

# View pending human gates
twin-pilot pending

# Approve a gate
twin-pilot approve <run-id> --comment "looks good"

# Non-interactive CI mode (set env vars)
export TWINPILOT_API_KEY=sk_live_examplekey
export TWINPILOT_TENANT=acme
export TWINPILOT_FACTORY=main
twin-pilot from-scratch "Automated bug fix"