How it works
The big picture, briefly.
What toil is made of and the promises it keeps. For specifics, such as setup steps, configuration keys and each integration, see the docs.
Alpha: APIs and flags may change before 1.0. The core described here and every integration on the board are built and tested.
One core
Two front doors, one set of commands.
Every command is defined once: its inputs, whether it writes, and its examples. The same definition is exposed as a CLI command and as an MCP tool, and both run exactly the same code.
A test walks every command and proves the two front doors accept the same inputs, send the same requests and return the same result, so they cannot drift apart.
Output
One JSON envelope, every time.
Every command prints exactly one envelope: ok, data, error and meta. Errors carry a stable code and a fix you can act on, never a stack trace. A mistyped command gets an envelope too, so an agent never has to read help text to learn it typed something wrong.
Configuration
Your environment, then your config.
Settings come from TOIL_* environment variables first, then your own config in your home folder. Pipelines and agents configure toil without editing a file.
Nothing inside a repository can change where your credentials go or switch on writes. Knowledge about a body of work, such as its repositories, issue keys and environments, lives in dossiers. A dossier holds no secret and cannot switch on writes, and it only chooses among connections you set up yourself, so a team can share one in a repository.
Credentials
One token, pasted once, kept safe.
Every integration signs in with a long-lived token you generate once in the service itself. There are no browser logins, no OAuth pop-ups and no device codes.
Tokens live in exactly two places: your operating system's own credential store, or environment variables. Setting up a connection with toil connections add asks for the token without showing it and puts it in the store, with only a reference in your config. Environment variables always win, and are the way in for CI, containers and machines with no credential store. A token is never kept in the config file, and never appears on a command line or in output.
Safety
Reads are free. Writes need two yeses.
Anything that changes data needs writes switched on for that service in your own config, and --allow-write on the call. Over MCP, write tools are not even listed until writes are on.
--verbose lists every request a command made, with credentials removed, so you can see exactly what it touched.
MCP
A stand-in for servers you can’t install.
toil mcp serves over stdio and never opens a network port. Scope it with --areas to give an agent a small, focused set of tools, standing in for vendor MCP servers that are blocked or need a browser login.
Install
Nothing for application control to block.
toil is a single JavaScript file on the Node you already have: no executable, no native module and no install script. Every build is checked to import only Node’s own modules and to contain only the files it should.