The whorl command
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.
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:
curl -fsSL https://whorl.work/install | shThe 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
whorl loginThis 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, Tools, MCP servers and connectors and Plugins for what to write.
API tokens
A token lets a script or the CLI act as you.
- Open Settings → API tokens.
- Choose New token.
- Under Token name, enter a name, and choose what it can reach.
- Choose Make token.
- 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.