> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twill.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Create and manage Twill tasks, automations, and sandboxes from your terminal.

```bash theme={"theme":"github-dark"}
npm install -g @twillai/cli
```

Requires Node.js 18+. Running `twill` with no arguments opens an interactive TUI; every capability is also available as a plain command for scripting.

## Authentication

Create an API key in workspace **Settings → API Keys**, then:

```bash theme={"theme":"github-dark"}
twill login --api-key twill_xxx
twill whoami   # verify
twill logout
```

Credentials are stored in `~/.twill/credentials.json`. For CI or scripts, set the `TWILL_API_KEY` environment variable instead. Use `TWILL_BASE_URL` to target a self-hosted instance.

<Accordion title="Multiple workspaces (profiles)">
  Keys are workspace-scoped. Use named profiles to switch between workspaces:

  ```bash theme={"theme":"github-dark"}
  twill login --api-key twill_xxx --profile work
  twill tasks --profile work
  ```
</Accordion>

## Tasks

```bash theme={"theme":"github-dark"}
# create
twill task create --command "Fix the flaky signup test" \
  [--mode code|plan|ask|dev_env] \
  [--agent claude-code/opus] \
  [--effort low|medium|high|xhigh] \
  [--title "..."]

# inspect & iterate
twill tasks                       # list
twill task <slug>                 # details
twill task continue <slug> --message "also update the docs"
twill task logs <slug>            # stream live logs
twill task archive <slug>
twill resume <slug>               # open the task in the TUI
```

In the TUI, use `/tasks`, `/resume <slug>`, `/agent`, `/forks`, and `/exit`.

## Automations

```bash theme={"theme":"github-dark"}
twill automation create --title "Issue triage" \
  --message "Triage new GitHub issues: label, prioritize, summarize" \
  --cron "0 9 * * 1-5" [--timezone Europe/Paris]

twill automations                 # list
twill automation <id>             # details
twill automation edit <id> --cron "0 10 * * 1"
twill automation pause|resume|delete <id>
```

## Teleport

Pull a task's full context down to your machine and continue it in your local agent:

```bash theme={"theme":"github-dark"}
twill teleport <task-slug>        # writes a local Claude Code session
claude -r <sessionId>             # resume it
```

By default the session attaches to a matching project in `~/.claude/projects/`; use `--project <path>` to pick one explicitly.

## Sandbox access

```bash theme={"theme":"github-dark"}
twill ssh                         # SSH into the workspace VM
twill fork scratch                # fork the VM under a name, then SSH in
twill ssh scratch                 # reconnect to that fork
```

Forks are recorded in `~/.twill/forks.json`. Lifecycle: idle forks stop after 30 minutes, archive after 24 hours, and are deleted 7 days after last use. Fork names allow letters, digits, `-`, and `_`.