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

# Command line tool

> Keep a Markdown copy of your company brain on your computer for coding agents, and ask the brain questions from the terminal.

Coding agents such as Claude Code, Codex, and Cursor are best at reading files. The Hyperspell command line tool plays to that strength. It keeps an up-to-date folder of Markdown pages about your company, projects, people, and decisions on your machine, and tells your coding agents where to find it. Agents read the pages with the tools they already have, without a network call, and can still ask the brain a live question when the pages are not enough.

The tool has two parts, installed together:

* `hyperspell`, the sync tool. It runs in the background, keeps the Markdown folder current, and configures your coding agents.
* `hyperbrain`, the query tool. It lets you, or an agent, ask the brain a question, search it, or save a note from the terminal.

## Install

<Steps>
  <Step title="Get your install command">
    In the dashboard, open Settings, then Connect Agents, and choose CLI. The dashboard generates an install command that includes a one-time token tied to you. The token works once and expires after an hour, so generate a fresh one when you need it.

    <Frame caption="The CLI setup in the dashboard">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/hyperspell/images/agents/cli-install.png" alt="The Set up the CLI dialog showing a generated install command with a copy button" />
    </Frame>
  </Step>

  <Step title="Run it in your terminal">
    Paste the command into a terminal on your Mac or Linux machine. It looks like this, with your token in place of the placeholder:

    ```bash theme={null}
    curl -fsSL -X POST -H 'Content-Type: application/json' \
      --data '{"install_token":"YOUR_TOKEN"}' \
      'https://app.hyperspell.com/api/daemon/install.sh' | bash
    ```

    The installer sets up an isolated Python environment, installs both tools, saves your credentials, registers the sync tool to start automatically when you log in, and runs a first sync. It refuses to run as root.
  </Step>

  <Step title="Check the result">
    ```bash theme={null}
    hyperspell status
    ```

    This shows when the brain last synced, where the files are, and a log of the changes the installer made to your agent configuration.
  </Step>
</Steps>

<Note>
  Prefer to install by hand? The query tool is on PyPI: `uv tool install hyperspell-brain` or `pipx install hyperspell-brain`, then `hyperbrain login`. The sync tool is only distributed through the dashboard install command.
</Note>

## Sign in from another machine

If you install on a second machine, or your credentials expire, run:

```bash theme={null}
hyperspell login
```

The tool prints a short code and opens a page in your browser. Approve the login there, and the terminal picks it up on its own.

```mermaid theme={null}
sequenceDiagram
    participant T as Terminal
    participant H as Hyperspell
    participant B as Your browser
    T->>H: Request a device code
    H-->>T: Code + approval link
    T->>B: Open approval page
    B->>H: You approve the code
    loop every few seconds
        T->>H: Is it approved yet?
    end
    H-->>T: Credentials
    T->>T: Save to ~/.hyperspell/config.toml
```

The approval page shows the code, the app it is for, and where the request came from. It asks you to confirm that you started the login yourself on your own device. If someone sends you an approval link by email or chat, do not approve it. Codes work once and expire after ten minutes.

<Frame caption="The device approval page">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/hyperspell/images/agents/cli-approve.png" alt="The Approve Device Login page with the app name, a confirmation checkbox, and an Approve button" />
</Frame>

## What gets installed

The tool writes to a few well-defined places.

| Location                                                      | What it holds                                                                                                                                                                    |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~/.hyperspell/`                                              | Your credentials, logs, and the canonical copy of the synced pages. Readable only by your user.                                                                                  |
| `~/Hyperspell/`                                               | A readable mirror of the pages, so agents running in a sandbox or container can read them too.                                                                                   |
| `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.cursorrules` | A short managed block telling each agent where the brain lives and when to use it. The block sits between two marker comments, and the tool never touches anything outside them. |
| Claude Desktop and Claude Code configuration                  | A registration for the Hyperspell MCP server, so those agents can also ask the brain live questions.                                                                             |

Once installed, a coding agent can answer "what does the billing service do and who owns it?" by reading `~/Hyperspell/`, and can fall back to `hyperbrain ask` for anything the pages do not cover.

<Warning>
  On a computer with several user accounts, everyone with an account can read the `~/Hyperspell/` mirror. If that is a concern, run the install with `--no-visible-mirror`, or set `visible_mirror = false` in `~/.hyperspell/config.toml`. Agents then read the private copy instead.
</Warning>

## Ask from the terminal

The query tool works for people and for agents alike.

```bash theme={null}
# Ask a question and get a cited answer
hyperbrain ask "who owns the mobile release process?"

# Search for documents without an answer
hyperbrain search "Q3 pricing experiment"

# Save something worth remembering
hyperbrain remember "The staging database is refreshed from production every Sunday night."

# Check your setup
hyperbrain doctor
```

`hyperbrain help --agent` prints the whole command surface as one short document, which is handy to paste into an agent's instructions.

## Keep it up to date

The sync tool checks for a new version of itself and of the query tool once a day and upgrades within the supported range. `hyperspell update` forces a check. `hyperbrain update` upgrades the query tool by itself.

Other commands you may need:

| Command                     | What it does                                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `hyperspell status`         | Show sync state, file locations, and recent actions.                                                    |
| `hyperspell sync --once`    | Sync now and exit.                                                                                      |
| `hyperspell search "query"` | Search the synced pages locally.                                                                        |
| `hyperspell uninstall`      | Remove the tool and its autostart entry. Add `--purge` to also delete the synced files and credentials. |

## Brain on disk, or not

Some organizations do not want a copy of the company brain sitting on employee laptops. The sync tool supports a lean mode for this. In lean mode it still installs the query tool and registers the MCP server with your agents, so they can ask the brain live questions, but it syncs no pages to disk and removes any it previously synced.

Admins can require lean mode for the whole organization from Settings. When that policy is on, every install is lean and the option cannot be turned off on individual machines. Individuals can also choose lean mode for their own install with `--no-context-docs`.

## Troubleshooting

**The install command fails immediately.** The token works once and expires after an hour. Generate a new one from the dashboard. If you are on a machine where you are root, the installer stops on purpose; run it as a normal user.

**Claude Code does not seem to know about the brain.** Open a new session so it re-reads `~/.claude/CLAUDE.md`, and check `claude mcp list` shows the Hyperspell server. `hyperspell status` lists what the installer configured.

**The pages look stale.** Run `hyperspell sync --once` and then `hyperspell status`. If the sync tool is not running, `hyperspell login` re-registers it to start automatically.

**I want everything gone.** `hyperspell uninstall --purge` removes the tools, the synced files, the credentials, and the managed blocks in your agent configuration files.