> ## Documentation Index
> Fetch the complete documentation index at: https://to11.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> The to11 CLI keeps your company's skills current on your machine, and uploads your Claude Code sessions to a project.

The **to11 CLI** is a single binary, `to11`. It does two things:

* keeps the [skills](https://to11.ai/docs/skills/concepts.md) your company publishes current in the directories your coding agent reads;
* uploads your Claude Code [sessions](https://to11.ai/docs/sessions/overview.md) to a project, by hand with `to11 session sync` or after every response with auto-sync.

It is how skills are **created and changed**. The browser reads them; the CLI writes them — see [Reading a skill in the dashboard](https://to11.ai/docs/skills/concepts.md#reading-a-skill-in-the-dashboard) for the other half.

## Where it comes from

The binary is published for Linux and macOS, on x86-64 and arm64. A [Homebrew](https://brew.sh) formula lives in the [`to11ai/tap`](https://github.com/to11ai/homebrew-tap) tap, an [asdf](https://asdf-vm.com) plugin lives at [`to11ai/asdf-to11`](https://github.com/to11ai/asdf-to11), and every [release](https://github.com/to11ai/to11-cli/releases) carries the archives and a `checksums.txt` directly. There is no Windows build yet.

[Receiving skills](https://to11.ai/docs/skills/receiving-skills.md#install-the-cli) has the commands.

## Getting it configured

`to11`, with no arguments, links the location you run it in and then syncs it. Inside a git repository it links the repository; outside one, your home. It signs you in through a browser when nobody is, asks only what it cannot work out — the project, whether to change the targets, the to11 plugin — writes `skills.yaml`, and fetches your skills. Every later run in a linked location is the sync, and asks nothing. [`to11 link`](https://to11.ai/docs/reference/cli/commands#to11-link) does the same link without the sync, and takes each answer as a flag.

Without a terminal, or when it detects a coding agent, it asks nothing: what it still needs comes back as one [`action_required`](https://to11.ai/docs/reference/cli/non-interactive) object, with commands that finish the link. On a machine where nobody signs in, such as CI, write the [configuration](https://to11.ai/docs/reference/cli/configuration.md) yourself and set `TO11_API_KEY`.

`to11 ui` is a full-screen view of the same setup.

See [Receiving skills](https://to11.ai/docs/skills/receiving-skills.md) for the walkthrough, and [`to11 link`](https://to11.ai/docs/reference/cli/commands#to11-link) for what each question decides.

## What it puts where

| Path | Holds |
| - | - |
| `~/.to11/skills.yaml` | your [configuration](https://to11.ai/docs/reference/cli/configuration.md) |
| `~/.to11/.skills.state.json` | what the CLI last wrote, per file |
| `~/.to11/credentials.json` | your credential, alone, at mode `0600` |
| `~/.to11/sessions.yaml` | where your Claude Code sessions go, and whether they are sent automatically; see [`sessions.yaml`](https://to11.ai/docs/reference/cli/configuration#sessionsyaml) |
| `~/.to11/.sessions.state.json` | how far each Claude Code transcript has been sent |
| `~/.claude/skills/<slug>` | installed skills, for Claude Code |
| `~/.agents/skills/<slug>` | installed skills, in the portable form |

Configuration never contains a secret, which is what makes a repository's copy safe to commit.

`$TO11_HOME` moves the first five. A repository's own configuration lives at `<repo>/.to11/skills.yaml`, and **both apply at once** — see [Configuration](https://to11.ai/docs/reference/cli/configuration.md).

## Staying current

An automatic refresh is a cache read, and `cacheTtlSeconds` is the window: inside it there is nothing to do and no request is made. It syncs when the window has passed, or when a configuration file that governs your machine has changed since the last write.

The refresh runs from a hook the [to11 plugin](https://github.com/to11ai/to11-code-plugin) carries, which `to11`, `to11 link` and `to11 ui` offer to install for Claude Code and Codex, where it finds them. A repository can never change how often your refresh runs: a team decides which skills apply to work in their repository, never how a colleague's agent behaves.

An automatic refresh **does not block the work that triggered it**. An update reaches the agent on the following message regardless, because the agent resolves a skill independently of when the file is written.

The exception is a session opening where a configuration has never synced, such as a fresh clone or a new worktree: none of its skills are installed yet, so the session-start refresh syncs before the session starts. It does this once per location — a sync that fails still counts, so a machine that cannot reach to11 waits on one session start, not every one — and for under a minute. When your sign-in is about to be renewed, that session start leaves the sync to the background, as for any other refresh.

**A refresh that fails is silent.** It writes nothing to either stream, and records nothing for a later command to report. See [Failing while nobody is watching](https://to11.ai/docs/reference/cli/errors.md#failing-while-nobody-is-watching).

`to11 skill sync` ignores the window entirely — an explicit sync always runs.

## What it never does

* **Touch a directory it did not create.** The state file records what the CLI wrote, per file; anything else in the same directory is never read and never removed. It is listed once — as `unmanaged`, or, when it stands exactly where a configured skill would go, as a `conflict` naming the path.
* **Replace something you edited.** A file you changed inside an installed skill makes that skill a local variant, and sync leaves the whole of it alone until you commit it with `to11 skill store` or discard it with `to11 skill sync --force`.
* **Delete a file you changed or added, on the way past.** When configuration stops asking for a skill — or for one of the targets it went to — only the files the CLI wrote and nobody changed are removed. Every other file stays, and so does the directory holding it, reported as `orphaned` on every run until it is empty; no flag removes it. A directory the CLI cannot read is reported and left whole.
* **Write to the platform unless you asked.** Only [`to11 skill store`](https://to11.ai/docs/reference/cli/commands#to11-skill-store), and [`to11 skill import`](https://to11.ai/docs/reference/cli/commands#to11-skill-import) when you tell it to upload a folder, store a version. A store moves the skill's one label, `latest`, which everyone following the project receives on their next sync.
* **Print your credential.** Not in the process list, not in a log, not in the terminal.

> [!NOTE]
>
> **Hidden files inside an installed skill are not compared.**
>
> The CLI skips dot-prefixed entries when it compares a skill against what it wrote, which is what stops a `.DS_Store` an agent or your OS drops into a skill directory from marking it `changed` and blocking every published update after it. So a hidden file you add, or edit when the CLI did not write it, never marks a skill `dirty`. It is not deleted either: when the skill leaves your configuration, it stays with the directory, which reads `orphaned`. The one exception is a `.DS_Store` written by macOS Finder, which holds only how Finder displays the folder; it is removed with the skill.

## Next steps

> [card] [Commands](https://to11.ai/docs/reference/cli/commands.md)
>
> Every command, its flags, its conflicts, and what each deliberately does not do.

> [card] [Configuration](https://to11.ai/docs/reference/cli/configuration.md)
>
> The file that decides what you receive — including how to disable a skill.

> [card] [Output formats](https://to11.ai/docs/reference/cli/output.md)
>
> Plain versus JSON, and what the JSON contract promises.

> [card] [Errors & exit codes](https://to11.ai/docs/reference/cli/errors.md)
>
> What a failure looks like, and what keeps working when one happens.

> [card] [Non-interactive mode](https://to11.ai/docs/reference/cli/non-interactive.md)
>
> When the CLI does not prompt, and the object it answers with instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.