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

​
Tasks

# Create a task
twill task create --command "Fix the login bug" --repository owner/repo

# 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)
--repositoryTarget repo as owner/repo (required)
--branchBase branch (optional)
--modecode, plan, ask, or dev_env (optional)
--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" \
  --repository-url https://github.com/owner/repo \
  --base-branch main \
  --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>
If you run twill teleport from within the matching repo, it auto-detects the Claude Code project directory. Otherwise, use --project <path> to specify the project path manually.

​
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