Only for a person at a terminal
The menu opens only when you run toil with no arguments and both stdin and stdout are a terminal, outside CI. Anything else,
an agent, a script, a pipe or toil mcp, gets the plain JSON CLI: one envelope on stdout. The menu can change your
connections and turn writes on, which agents over MCP never can.
Home
Home shows what this folder is (the repository, its branch and remote, read from .git without running git), how many
connections you have and how the last test of each went, and a needs attention list: a config file that won't load, its
warnings, a sign-in that was rejected, or no connections yet. Each of those rows opens the screen that fixes it.
Services
Services, the first entry on home, is every command toil has, laid out the way you type it:
toil <service> <resource> <action>. Pick a service (the ones you have a connection for come first), then what
to act on (an issue, a work item, a pull request), then the action, and the screen shows the command with its arguments and flags.
Run it asks for each id, then a line of flags with the required ones filled in, and runs that line. A command that
changes something shows the line with --allow-write and asks first; it still needs writes on for the connection.
Find a command searches every service by name or description.
Every step is a real command
The menu has no logic of its own. Each action runs a toil connections command in the same process, prompting on your terminal,
and the result screen shows the command line it ran and what came back. Run the same line yourself any time.
| In the menu | It runs |
|---|---|
| Add a connection | toil connections add <name> --area <area>, then toil connections test <name> |
| Test a connection, or all of them | toil connections test <name>, once per connection |
| Sign in again | toil connections login <name>, then toil connections test <name> |
| Turn writes on or off | toil connections writes <name> on, asks you to type the name |
| Make a connection its area's default | toil connections default <name> |
| Remove a connection | toil connections remove <name>, after you type the name |
Adding a connection
Four steps: pick the service, name the connection (the area's own name is suggested), answer the questions that service needs, with its defaults filled in and the secret read without echo, then a live test. Before anything is saved you see every setting and where the secret goes. The secret goes to your operating system's credential store, with only a reference in your config. If there is already a default connection for that area, you're asked whether this one should take over. Esc goes back a step without losing what you typed.
The test sends one cheap, authenticated read, such as Jira's /rest/api/2/myself, through the same code every command uses,
so a rejected token fails here the way it would later. For an area with no such check, the test confirms the settings and the secret and
says it sent nothing.
Writes need the name typed
Turning writes on for a connection asks you to type its name. There is no flag that skips the question, and without a terminal the command
refuses and tells you to set "writes": true yourself. Removing a connection asks for the name too. Even with writes on, every
write still needs --allow-write on the call. How writes are gated.
Connecting an agent
Pick Claude Code, Codex or VS Code, tick the areas it should see (none means every area), and the menu prints the snippet that registers
toil mcp --areas … with it. It never edits another program's config.
Agent skills
One submenu for everything an agent reads from its skills folder. Skill plugins adds a marketplace, a git repository
of skill plugins, installs one for the agent and place you pick, and switches installed skill plugins on and off. View installed
skills lists every skill in every agent folder. Install the toil skill runs toil skill install for
the agent and place you pick; toil keeps that copy current from then on.
Dossiers
New to dossiers? What is a dossier? explains them, with diagrams.
This folder says which dossier applies where you are and why: your repository's folder or remote is one of its repos, or it's checked into the repository. If none does, it offers to create one for this repository or add the repository to one of yours.
Create takes six steps: a name, the repositories from a scan (as checkboxes), each area with the connection it uses (or a new connection, through the same wizard as above), the Jira fields, Confluence spaces, Sonar or Azure DevOps projects found on that connection (as checkboxes), the environments and their resources, then a review that shows the whole dossier and checks it. Review groups what the check finds and offers each fix in place: relink an area, add the connection it names, remove a section toil has no area for, take a credential out of a stored remote, adopt it, or look its values up on the service. Edit shows the commands a change runs before you save it.
Binding a dossier to a connection with writes on asks you to type the connection's name, as turning writes on does, and importing a dossier
whose bindings do asks for the dossier's name. Import lists every connection the file names that you don't have yet, each with a row that
adds it. Export writes into this repository's .toil/dossiers/ or to a file, and never commits. Deleting asks for the name.
| In the menu | It runs |
|---|---|
| This folder | toil dossiers context |
| Create: name | toil dossiers init <name> |
| Create: repositories | toil repos scan, then toil dossiers add-repo <name> <folder> for each one ticked |
| Create: an area and its connection | toil dossiers link <name> <area> --connection <connection>, or --host <host> |
| Create: discovery | toil jira issue fields --discover --custom-only --dossier <name>, then toil dossiers field for each one ticked |
| Create: an environment | toil dossiers env <name> <env> <area> --connection <connection> |
| Review | toil dossiers check <name>, and toil <area> check-dossier |
| Remove a section | toil dossiers unlink <name> --area <area>, after you type the area |
| Export | toil dossiers export <name> --repo <dir>, or --file <path> |
| Import | toil dossiers import <file>, after toil dossiers check <file> |
| Delete | toil dossiers remove <name>, after you type the name |
Brick breaker, retired
Brick breaker has been retired: a paddle on a character grid never felt right. There may be something else in the menu for the minutes a build takes. It is not listed, it is not a command or an MCP
tool, and HR has asked us not to say how to find it. If your config file grows a sealed "game" entry, that's
the menu's doing: it holds nothing but a game's progress, sealed so it can't be edited by hand or copied to another account. That
guards against tampering, not prying: anyone who can read your files can open it. No command reads it, and deleting it only starts
the game over.
Terminals
The splash animates in Windows Terminal, macOS Terminal and Linux terminals. The legacy Windows console host, NO_COLOR,
TOIL_NO_ANIMATION, TERM=dumb and a window smaller than 40 by 12 get the still frame. Where Unicode isn't safe, the
legacy console host or TOIL_ASCII, everything is drawn in plain ASCII. Long lists scroll on a short window; on a narrow one, text
wraps and table rows are cut at the edge rather than wrapping into each other.
| Key | Does |
|---|---|
Up / down, or j / k | Move |
Enter, or 1 to 9 | Choose |
Space | Tick a box: areas for an agent, repositories or discovered values for a dossier |
Esc | Back one screen, keeping your answers |
q | Quit from anywhere but a text field |
Ctrl+C | Cancels the command running; twice in two seconds leaves the menu |