twill to open the interactive terminal UI, or use the commands below in scripts. Add --help to any command for its options.
Authentication
Create a key in a cloud workspace under Settings → API keys, then sign in and paste it when asked:~/.twill/credentials.json. For CI, set TWILL_API_KEY instead, and TWILL_BASE_URL for another Twill URL. twill logout removes the saved key.
Use more than one workspace
Use more than one workspace
Give each login a profile, then pick one per command or switch the default:
Interactive UI
twill opens a composer: describe a task and press Enter. It shows your recent tasks, and / lists commands.
Start any message with
/plan to have the agent plan first, or /goal <objective> to keep it working toward a goal across turns. Other slash commands your agent supports, such as /compact, pass through. Esc stops a running turn; Ctrl+C twice exits. twill resume <task-slug> opens a task directly.
Tasks
task create accepts --agent <provider/model> (for example claude-code/opus or codex/gpt-6.1-sol), --effort <level>, and --title. Without them, the workspace’s routing picks the agent. --follow streams the run until it finishes, and task <task-slug> --web opens the task in your browser.
Fork. Each cloud task runs in its own fork of the workspace environment. Pass --no-fork to run it in the main environment instead, so what it installs or configures stays for future tasks. This is how you set up or fix the environment. It’s chosen when the task is created; follow-ups keep it.
Plans. Put /plan at the start of the text, then review the plan with twill task <task-slug>. twill task approve <task-slug> implements it, the same as Implement in the app; task continue refines it instead.
Follow-ups keep the task’s agent. task continue --agent can switch to another model of the same agent, and --effort changes the reasoning effort. A follow-up interrupts a running turn. Answer permission and other questions in the Twill task chat.
Commands print readable output in a terminal and JSON when piped or with --json.
Automations
Create a recurring cloud task with a cron expression. It uses your computer’s time zone unless you pass--timezone:
--no-fork to run an automation in the main environment (--fork turns it back). See Automations for setup and plan requirements.
Run agents on a computer
twill computer connects the computer you run it on, such as a Mac mini without a screen, and runs agents there. You then send it tasks from Twill on your other devices. See Headless computer.
connect offers to keep the computer running in the background, also after restarts.
Sandbox access
~/.twill/forks.json, and only the member who created a fork can connect to it. Treat scratch environments as temporary and push any work you want to keep: forks pause when idle and are deleted after 3 idle days or 7 days in total (see Fork lifecycle).