# The jot CLI

> Log in once, bind a repo, read, reply to and resolve feedback from the terminal, and run the MCP server.

Source: https://docs.usejot.co/docs/ai/cli

`jot` is one small native program: the terminal commands, the setup that
gives your coding agent `/jot`, and the MCP server itself (`jot mcp`).

Using Claude Code? [The Jot plugin](/docs/ai/mcp#connect) is one line, and runs this CLI for you.

## Install

```bash
npm i -g @usejot/cli     # then type jot
```

Or without installing, prefix any command with `npx @usejot/cli`:

```bash
npx @usejot/cli login
```

npm picks the build for your machine: macOS (Apple silicon and Intel), Linux
(x64 and arm64) and Windows x64. Node 18 or later runs the installer; `jot`
itself needs nothing else.

<Callout title="macOS already has a jot">
  macOS ships an unrelated `/usr/bin/jot` that prints number sequences. npm's global folder comes
  first on a normal `PATH`, so `jot` is this one; if `jot --version` prints `jot: illegal option`,
  put npm's folder (`npm prefix -g`, then `/bin`) ahead of `/usr/bin`, or use `npx @usejot/cli`.
</Callout>

## Get started

```bash
jot login     # the browser opens; pick a workspace
jot init      # in a repo: .jot.json, .mcp.json, /jot, the jot skill and AGENTS.md
jot whoami    # check: the profile, workspace and projects in use
```

`jot init` writes, in the repo root:

* `.jot.json`: the profile and project. No secrets, safe to commit.
* `.mcp.json`: the `jot` MCP server, with **no token inside**. It runs
  `jot mcp` when `jot` is installed, `npx -y @usejot/mcp` when it is not;
  both find the token through `.jot.json`. An old `JOT_API_TOKEN` in it is
  removed, and `jot init` says so.
* `.claude/commands/jot.md`: the `/jot` command for Claude Code.
* `.claude/skills/jot/SKILL.md`: the jot skill, [how an agent should work the queue](/docs/ai/agents).
* `AGENTS.md`: the same guide in a marked `<!-- jot -->` section, for Codex,
  Cursor and other agents. Only that section is ever rewritten; the rest of
  the file is yours.

A `/jot` command or skill you edited is left alone; `jot init --force`
replaces it.

## Commands

This reference is generated from the contract the CLI is built from.

| Command                                              | Does                                                                                  |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `jot login`                                          | connect this terminal to a workspace (opens the browser)                              |
| `jot init`                                           | in a repo: bind it to a project and add /jot for Claude Code                          |
| `jot list [--status S] [--json]`                     | open feedback, one line each (--status all for every state)                           |
| `jot show <id>`                                      | the full repro, as markdown                                                           |
| `jot status <id> <STATUS> [-m note]`                 | move it to IN\_PROGRESS, RESOLVED or APPROVED; the API applies the workspace's policy |
| `jot reply <id> -m "text"`                           | reply in the thread                                                                   |
| `jot watch [--once] [--json] [--interval 5] [--all]` | wait for new feedback and print it                                                    |
| `jot loop [--agent claude] [--fix]`                  | hand each new comment to an agent                                                     |
| `jot profiles`                                       | list them (\* is the default)                                                         |
| `jot use <name>`                                     | make one the default                                                                  |
| `jot logout <name>`                                  | forget one                                                                            |
| `jot whoami`                                         | the profile, workspace and projects in use                                            |
| `jot profile <name> <command…>`                      | run any command as that profile (same as --profile)                                   |
| `jot prompt`                                         | instructions to paste into Cursor, Codex or any agent                                 |
| `jot mcp`                                            | the MCP server, over stdio (what .mcp.json runs)                                      |
| `jot help \| --version`                              | this help, or the version                                                             |

| Command      | Flag                 | Does                                                       |
| ------------ | -------------------- | ---------------------------------------------------------- |
| `jot login`  | `-p, --profile name` | save as this profile name                                  |
| `jot login`  | `--api url`          | the API (default BACKEND\_API\_URL, then the hosted one)   |
| `jot login`  | `--app url`          | the dashboard (default JOT\_APP\_URL, then the hosted one) |
| `jot init`   | `--project id`       | bind this project instead of asking                        |
| `jot init`   | `--force`            | replace an edited /jot command or jot skill                |
| `jot list`   | `--status S`         | OPEN (default), IN\_PROGRESS, RESOLVED, APPROVED or all    |
| `jot list`   | `--json`             | print JSON                                                 |
| `jot status` | `-m, --message note` | post this note too                                         |
| `jot reply`  | `-m, --message text` | the reply                                                  |
| `jot watch`  | `--once`             | stop after the first new comment                           |
| `jot watch`  | `--json`             | one JSON object per line                                   |
| `jot watch`  | `--interval seconds` | poll interval, 1 or more (default 5)                       |
| `jot watch`  | `--all`              | on the first run, count what is already open as new        |
| `jot loop`   | `--agent claude`     | run headless with this agent                               |
| `jot loop`   | `--fix`              | let the agent edit, then resolve                           |
| `jot loop`   | `--interval seconds` | poll interval, 1 or more (default 5)                       |
| `jot loop`   | `--all`              | on the first run, count what is already open as new        |
| any          | `-p, --profile name` | run as this profile                                        |
| any          | `-h, --help`         | print the help                                             |
| any          | `-v, --version`      | print the version                                          |

`jot status` passes any status through; the API decides what this token may
set. Approval follows the workspace's policy, so `APPROVED` works only where
the workspace lets agents approve.

## Profiles

A profile is a workspace's API address and token, saved in
`~/.jot/config.json` (readable only by you; `JOT_HOME` moves the folder).
`jot login` names it after the workspace; `--profile office` names it
yourself. The first one is the default.

Which profile a command uses, highest first:

1. `--profile <name>` (or `jot profile <name> …`)
2. the `JOT_PROFILE` environment variable
3. the nearest `.jot.json`, walking up from the current folder
4. the default profile
5. `JOT_API_TOKEN` and `BACKEND_API_URL`, for setups from before profiles

A name from the first three that this machine does not have is an error,
never a quiet switch to another workspace.

### Two workspaces, or two accounts

Log in once per workspace, naming each profile. Signing in with a different
account works the same way: sign out of Jot in the browser (or use another
browser profile) before the second login.

```bash
jot login --profile office      # pick the company workspace
jot login --profile personal    # pick your own, or sign in as someone else
jot profiles                    # both, * marks the default
jot use personal                # change the default
```

Then run any command as either, without changing the default:

```bash
jot profile office list
jot --profile personal show cmv1x…
JOT_PROFILE=office jot watch
```

Each repo's `.jot.json` names its own profile, so `jot init` in your work repo
and in your side project keeps the two apart for you and for your agent.
`jot logout <name>` forgets a profile; revoke its token in
**Settings → Agents**.

## Watch

`jot watch` checks for new open feedback every 5 seconds (`--interval` to
change it) and prints each new comment as markdown, or one JSON line with
`--json`. `--once` exits after the first. The first run treats what is
already open as known, so only new feedback comes through; `--all` includes
it. What it has shown is remembered per profile in `~/.jot/state/`.

## Loop

Inside Claude Code, `/jot loop` is the loop: the agent runs `jot watch --once`,
proposes a fix, and waits for your OK (`/jot loop fix` skips the wait).

Headless, `jot loop --agent claude` runs [Claude Code](https://claude.com/claude-code)
once per new comment:

* **Propose (default):** `claude -p` in plan mode. The comment moves to
  `IN_PROGRESS` and Claude's plan is posted on it as a reply, for the team to
  approve.
* **`--fix`:** Claude edits the code (`acceptEdits`). When it succeeds the
  comment moves to `RESOLVED` and Claude's summary is posted as the reply.

Each comment prints one line, and the loop keeps going until Ctrl+C.

## The MCP server: jot mcp

`jot mcp` is the Jot MCP server, over stdio. Your agent starts it; you never
run it by hand. It serves the same six tools as `npx -y @usejot/mcp`, with
the same names and inputs, reads the token through the same profiles, and
sends the agent the [playbook](/docs/ai/agents) as its instructions.

```json
{
  "mcpServers": {
    "jot": { "command": "jot", "args": ["mcp"] }
  }
}
```

`jot mcp doctor` checks the token and the API, and prints a config to paste.
Setup for each agent is in [MCP for coding agents](/docs/ai/mcp).
