@twillai/cli

Run and manage Twill agent tasks from your terminal.

@twillai/cli gives you two workflows:

• Interactive mode (twill) for day-to-day agent chat
• Command mode (twill task ...) for scripts and automation

Install

npm install -g @twillai/cli

Or run without installing globally:

npx @twillai/cli@latest

Requirements:

• Node.js >=18
• A Twill API key

Quick start (2 minutes)

1. Create an API key in Twill.

2. Login once:

twill login --api-key <your_twill_api_key>

3. Start interactive mode:

twill

You can now create tasks, follow up, switch mode (code, plan, ask, dev_env), and stream progress live.

Most useful commands

Create a task

twill task create \
  --command "Refactor authentication middleware to remove duplicated logic" \
  --repository owner/repo \
  --branch main \
  --mode code

Continue a task in chat mode

twill resume <task-slug>

Inside resume:

• /mode plan|code|ask|dev_env sets default follow-up mode
• /plan <message> / /code <message> / /ask <message> / /dev_env <message> sends one-off mode messages
• /quit exits

Send one follow-up without entering chat

twill task continue <task-slug> --message "Please split this into smaller commits" --mode code

Stream job logs (JSON, script-friendly)

twill task logs <task-slug>

Teleport a task session to local Claude

twill teleport <task-slug>

This exports session files under ~/.claude/projects/-root-workspace and prints a resume command:

claude -r <session-id>

Useful auth patterns

Use profiles when you work across multiple workspaces:

twill login --api-key <key_a> --profile team-a
twill login --api-key <key_b> --profile team-b
twill task list --profile team-a

Or skip persisted credentials entirely:

export TWILL_API_KEY=<your_twill_api_key>
export TWILL_BASE_URL=https://twill.ai
twill task list

Scripting best practices

• Prefer non-interactive commands (task create, task continue, task logs) in CI
• Treat command output as JSON and parse with tools like jq
• Use --profile explicitly in automation to avoid surprises from local defaults
• Keep secrets in environment variables, never in shell history or committed files

Help

twill --help
twill --version