> ## 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

> Manage Twill tasks and automations from your terminal

## Install

```bash theme={"theme":"github-dark"}
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`:

```bash theme={"theme":"github-dark"}
twill login --api-key <your-key>
```

Credentials are stored in `~/.twill/credentials.json`. You can also set the `TWILL_API_KEY` environment variable instead.

```bash theme={"theme":"github-dark"}
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.

```bash theme={"theme":"github-dark"}
twill
```

Inside the TUI, type `/` to see available commands: `/tasks`, `/resume <slug>`, `/agent`, `/forks`, `/exit`.

## Tasks

```bash theme={"theme":"github-dark"}
# Create a task
twill task create --command "Fix the login bug"

# 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

| Flag        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `--command` | What to do (required)                                          |
| `--mode`    | `code`, `plan`, `ask`, or `dev_env` (optional)                 |
| `--agent`   | Agent provider/model, e.g. `claude-code/opus`, `codex/gpt-5.5` |
| `--effort`  | Reasoning effort: `low`, `medium`, `high`, or `xhigh`          |
| `--title`   | Task title (optional)                                          |

## Resume

Start a live interactive chat session with an existing task:

```bash theme={"theme":"github-dark"}
twill resume <slug>
```

## Automations

```bash theme={"theme":"github-dark"}
# Create a scheduled automation
twill automation create \
  --title "Daily lint check" \
  --message "Run lint and fix issues" \
  --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:

```bash theme={"theme":"github-dark"}
twill teleport <slug>
```

Then resume locally:

```bash theme={"theme":"github-dark"}
claude -r <sessionId>
```

By default `twill teleport` prompts you to pick from your existing Claude Code projects under `~/.claude/projects/`. Pass `--project <path>` to write directly to a specific project directory and skip the picker.

## Workspace sandbox

Each workspace has a long-lived sandbox that holds your connected repos and dev-environment state. You can open a shell into it directly, or create a named **fork** — a one-off sandbox cloned from the workspace sandbox that isn't tied to any task.

### SSH into the workspace sandbox

```bash theme={"theme":"github-dark"}
twill ssh
```

### Fork the workspace sandbox

Create a named fork (cloned from the current workspace sandbox state) and SSH into it:

```bash theme={"theme":"github-dark"}
twill fork scratch
```

Forks are recorded locally in `~/.twill/forks.json`, keyed by workspace. List them inside the interactive TUI with `/forks`.

### SSH into a fork

```bash theme={"theme":"github-dark"}
twill ssh scratch
```

Idle forks auto-stop after 30 minutes and auto-archive after 24 hours; `twill ssh <name>` resumes the sandbox automatically. Forks are auto-deleted 7 days after they stop being used.

Fork names must contain only letters, digits, `-`, and `_`.

## Profiles

Manage multiple workspaces with named profiles:

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

## Environment variables

| Variable         | Description                            |
| ---------------- | -------------------------------------- |
| `TWILL_API_KEY`  | API key (alternative to `twill login`) |
| `TWILL_BASE_URL` | Override API base URL                  |