Skip to main content

​
Install

npm install -g @twillai/cli
Requires Node.js 18+.

​
Authenticate

  1. Create an API key in your Twill workspace under Settings
  2. Run twill login:
twill login --api-key <your-key>
Credentials are stored in ~/.twill/credentials.json. You can also set the TWILL_API_KEY environment variable instead. 
twill whoami    # verify your identity
twill logout    # remove saved credentials

​
Interactive mode

Run twill with no arguments to open the interactive TUI where you can browse tasks, create new ones, and resume conversations. 
twill
Inside the TUI, type / to see available commands: /tasks, /resume <slug>, /agent, /forks, /exit.

​
Tasks

# Create a task
twill task create --command "Fix the login bug"

# List tasks
twill tasks

# View a specific task
twill task <slug>

# Send a follow-up message
twill task continue <slug> --message "Also update the tests"

# Stream job logs
twill task logs <slug>

# Archive a task
twill task archive <slug>

​
Create options

FlagDescription
--commandWhat to do (required)
--modecode, plan, ask, or dev_env (optional)
--agentAgent provider/model, e.g. claude-code/opus, codex/gpt-5.5
--effortReasoning effort: low, medium, high, or xhigh
--titleTask title (optional)

​
Resume

Start a live interactive chat session with an existing task: 
twill resume <slug>

​
Automations

# Create a scheduled automation
twill automation create \
  --title "Daily lint check" \
  --message "Run lint and fix issues" \
  --cron "0 9 * * 1-5"

# List automations
twill automations

# View, edit, pause, resume, or delete
twill automation <id>
twill automation edit <id> --cron "0 8 * * *"
twill automation pause <id>
twill automation resume <id>
twill automation delete <id>

​
Teleport

Export a task’s Claude session locally so you can continue in Claude Code: 
twill teleport <slug>
Then resume locally: 
claude -r <sessionId>
By default twill teleport prompts you to pick from your existing Claude Code projects under ~/.claude/projects/. Pass --project <path> to write directly to a specific project directory and skip the picker.

​
Workspace sandbox

Each workspace has a long-lived sandbox that holds your connected repos and dev-environment state. You can open a shell into it directly, or create a named fork — a one-off sandbox cloned from the workspace sandbox that isn’t tied to any task.

​
SSH into the workspace sandbox

twill ssh

​
Fork the workspace sandbox

Create a named fork (cloned from the current workspace sandbox state) and SSH into it: 
twill fork scratch
Forks are recorded locally in ~/.twill/forks.json, keyed by workspace. List them inside the interactive TUI with /forks.

​
SSH into a fork

twill ssh scratch
Idle forks auto-stop after 30 minutes and auto-archive after 24 hours; twill ssh <name> resumes the sandbox automatically. Forks are auto-deleted 7 days after they stop being used. Fork names must contain only letters, digits, -, and _.

​
Profiles

Manage multiple workspaces with named profiles: 
twill login --api-key <key> --profile work
twill tasks --profile work

​
Environment variables

VariableDescription
TWILL_API_KEYAPI key (alternative to twill login)
TWILL_BASE_URLOverride API base URL