# The whorl command

> Install the whorl command, sign in, pull and push agent setup, check a setup folder, and create API tokens for scripts.

Source: https://docs.whorl.work/reference/cli

`whorl` is a command-line tool for people who edit agent setup as files, write skills and tools on their own computer, or run scripts that act as them. You do not need it to use Whorl. Everything it does for setup is also available in Settings and by asking an agent. See [Agents and setup](/agents/setup).

Every Thread's Environment already has `whorl` installed and signed in as the person the agent acts for, so an agent can use these commands without you doing anything.

## Install

On macOS or Linux, run this in a terminal:

```sh
curl -fsSL https://whorl.work/install | sh
```

The script picks the right program for your computer, checks its checksum and installs it into `~/.local/bin`, or into the folder named by `WHORL_INSTALL_DIR` if you set one. It tells you if that folder is not on your `PATH`. A Whorl deployment at another address serves its own install script from that address.

Run `whorl update` any time to replace the program with the latest release from the Whorl you use.

## Sign in

```sh
whorl login
```

This opens a page in your browser. Check that you started it, choose **Approve**, and return to the terminal. Use `--no-browser` to print the address instead of opening it.

| Command                                         | Does                                                              |
| ----------------------------------------------- | ----------------------------------------------------------------- |
| `whorl login`                                   | Signs this computer in.                                           |
| `whorl logout`                                  | Signs this computer out and forgets its token.                    |
| `whorl whoami`                                  | Shows the person, the company and the server.                     |
| `whorl switch <org>`                            | Chooses which company `whorl` works in.                           |
| `whorl devices list` and `whorl devices revoke` | Lists the computers signed in to your account, and signs one out. |
| `whorl doctor`                                  | Checks that you are signed in and Whorl is reachable.             |

You can also see and sign out your devices under **Signed in** in **Settings → Profile**.

## Work on setup files

Setup lives in layers: `organization`, `personal` and `space:<id>`. A Captain's files are in its folder in Files.

| Command                                 | Does                                                                                                                                                                    |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `whorl setup pull <layer> [dir]`        | Copies a layer's setup files from Files into a folder on your computer.                                                                                                 |
| `whorl setup push <layer> [dir]`        | Saves the folder's changes back. Add `--dry-run` to see them first, and `--delete` to remove files you deleted. It refuses files that changed in Files since your pull. |
| `whorl check [path]`                    | Checks a setup folder the way Threads load it, and lists problems. It exits with an error when something is wrong.                                                      |
| `whorl status`                          | Shows each layer and what loaded or was skipped.                                                                                                                        |
| `whorl skills new <name>`               | Creates a skill folder with valid front matter.                                                                                                                         |
| `whorl tools new <name>`                | Creates a custom tool with its description file and code.                                                                                                               |
| `whorl tools run <name> --input <json>` | Runs a custom tool on your computer with the same input checks.                                                                                                         |
| `whorl plugins new <name>`              | Creates a plugin folder with a starter skill.                                                                                                                           |

A normal session is: pull a layer, edit it, run `whorl check`, then push. The change takes effect on the next run. You can only push to a layer you are allowed to change.

`whorl tools run` has no access to secrets or Whorl actions outside a real run, so a tool that uses them fails on your computer with a message saying so. Test that part by calling the tool in a Thread after you push.

See [Skills](/agents/skills), [Tools, MCP servers and connectors](/agents/tools) and [Plugins](/agents/plugins) for what to write.

## API tokens

A token lets a script or the CLI act as you.

1. Open **Settings → API tokens**.
2. Choose **New token**.
3. Under **Token name**, enter a name, and choose what it can reach.
4. Choose **Make token**.
5. Copy the token. Whorl shows it only once, and anyone who has it can act as you.

To stop a token, choose **Revoke token**. Anything using it stops working right away, and you cannot undo this. The list shows when each token was **Last used** and when it **Expires**.

On the command line, `whorl tokens list`, `whorl tokens create` and `whorl tokens revoke` do the same, and `whorl auth token` prints the token the CLI is using, for scripts.

## Related

- [Agents and setup](/agents/setup)
- [Settings](/reference/settings)