@twillai/cli

Twill from your terminal:

• Cloud tasks: start, follow and continue tasks in a cloud workspace, in an interactive UI (twill) or as scriptable commands (twill task …).
• Automations: create and manage recurring cloud tasks.
• Computers: connect a computer, such as a Mac mini or Linux box you reach over SSH, and run agents on it with no screen and no Twill Desktop. You then send it tasks from Twill on your other devices.

Install

npm install -g @twillai/cli

Requires Node.js 22 or later. Running a computer works on macOS and Linux.

Cloud tasks

Create an API key in a cloud workspace (Settings → API keys), then:

twill login                 # paste the key when asked
twill                       # interactive UI

In the interactive UI, type what you want done and press Enter. Commands start with /:

• Home: /model (agent, model and effort), /fork (off: new tasks run in the main environment), /tasks, /resume <slug>.
• In a task: /approve (implement the proposed plan), /model (another model or effort for the next messages), /open (in the browser), /more (older messages).

Start a message with /plan to have the agent plan before it changes anything, or /goal <objective> to keep it working toward a goal across turns. Your agent's other slash commands (for example /compact or /review) pass through too. Esc stops a running turn.

The same things as commands:

twill task create "Fix the flaky signup test" --follow
twill task create "/plan Add rate limiting to the API"
twill task approve add-rate-limiting-x1y2 --follow
twill task continue fix-the-flaky-signup-test-a1b2 "Also cover the empty state"
twill tasks
twill task <slug> [--web]
twill task logs <slug>
twill task stop <slug>
twill task archive <slug>
twill resume <slug>           # open it in the interactive UI

task create options: --agent <provider/model> (for example claude-code/opus or codex/gpt-6.1-sol), --effort <level>, --title, and --no-fork to run in the workspace's main environment instead of the task's own fork (use it to set up or fix the environment). Follow-ups keep the task's environment and agent; --agent can switch to another model of the same agent.

Output is readable in a terminal and JSON when piped or with --json, so scripts can use jq.

Automations

twill automation create --title "Issue triage" \
  --message "Triage new GitHub issues: label, prioritize, summarize" \
  --cron "0 9 * * 1-5"            # this computer's time zone unless --timezone
twill automations
twill automation edit <id> --cron "0 10 * * 1" --no-fork
twill automation pause|resume|delete <id>

Run agents on this computer

Connect a computer to your Twill account, add project folders, and keep the runner going. Tasks you start for those projects from Twill (desktop, web or phone) run here, with this computer's agent logins.

twill computer connect               # approve the link from any signed-in device
twill computer add ~/code/my-app     # add a project (repeat for more)
twill computer status

• After connecting, connect offers to keep the runner going in the background, also after restarts (--service installs it without asking, --no-service skips it). twill computer service install|uninstall does the same later, and twill computer start runs it in the foreground instead (Ctrl+C stops).
• Sign the agents in once on this computer: claude auth login, codex login --device-auth, or opencode auth login.
• On macOS the runner keeps the computer from idle-sleeping while it runs (--allow-sleep to opt out); the service starts when you log in, so turn on automatic login for a Mac that should recover from a power cut. On Linux, sudo loginctl enable-linger $USER keeps the service running while you're logged out.
• twill computer logs -f, twill computer projects, and twill computer disconnect cover the rest.

The computer shares Twill Desktop's connection, so installing Desktop on it later doesn't add a second computer. The first run installs the runner's one dependency into ~/.twill/runner/.

Logins and profiles

twill login --api-key <key> --profile team-a
twill profiles                # list saved logins
twill profiles use team-a
twill tasks --profile team-a

In CI, set TWILL_API_KEY (and TWILL_BASE_URL for another Twill URL) instead of logging in.

Cloud environment

twill ssh                     # the workspace's main environment
twill fork scratch            # a disposable fork, then SSH in
twill ssh scratch

Run twill --help, or twill <command> --help, for every option.