CLI reference

22 commands, listed alphabetically. mossbear --help prints the same list at the terminal.

artifacts

Read, create, update, file and archive Mossbear artifacts, read their feedback, and relink a moved file.

create

Create an artifact from a file, optionally filed into a bundle.

mossbear artifacts create --file <value> --name <value>

--json — print the validated response as JSON.
--dashboard-url <value> — override the dashboard base URL.
--file <value> — uTF-8 file containing the content.
--name <value> — artifact name.
--bundle <value> — destination bundle slug. Optional unless your credential is scoped to bundles.

feedback

Read the open comments on one or more artifacts and, for a guide, its grading.

mossbear artifacts feedback <artifact>

<artifact> — artifact URL or id; name up to 25 to read them in one call.
--json — print the validated response as JSON.
--dashboard-url <value> — override the dashboard base URL.
--cursor <value> — continue from nextCursor of the previous page (one artifact only)

file

File an artifact into a bundle, or take it out with --remove.

mossbear artifacts file <artifact> --bundle <value>

<artifact> — artifact URL or id.
--json — print the validated response as JSON.
--dashboard-url <value> — override the dashboard base URL.
--bundle <value> — bundle slug.
--remove — remove the artifact from the bundle instead of adding it.

history

List saved versions of an artifact with hashes and pagination.

mossbear artifacts history <artifact>

<artifact> — artifact URL or id.
--json — print the validated response as JSON.
--dashboard-url <value> — override the dashboard base URL.
--before <value> — return versions older than this one, from nextCursor.
--limit <value> — page size, at most 200.

read

Read one artifact by URL or id, current or at a saved version.

mossbear artifacts read <artifact>

<artifact> — artifact URL or id.
--json — print the validated response as JSON.
--dashboard-url <value> — override the dashboard base URL.
--version <value> — saved version number; omit for current content.

relink

Point a synced artifact’s mapping at the path you moved its file to.

mossbear artifacts relink <old> <new>

<old> — path the artifact is currently mapped to (the one mossbear refresh reports as missing)
<new> — path the file now lives at.

Both are required. The command roots itself at the repo root, the same way refresh and status do, so it rewrites the same placement file the sync reads even when you run it from a subdirectory. It exits non-zero when it refuses, so a script that relinks in a loop does not read a refusal as success.

update

Replace an artifact from a file, against the version you read.

mossbear artifacts update <artifact> --file <value> --expected-version <value>

<artifact> — artifact URL or id.
--json — print the validated response as JSON.
--dashboard-url <value> — override the dashboard base URL.
--file <value> — uTF-8 file containing the full replacement content.
--expected-version <value> — current version actually read; a stale edit is refused.

comment

Leave a comment on an artifact or one of your sessions, reply to a comment, or resolve one you acted on, as the agent session you are running in (writes to the dashboard).

mossbear comment <text>

<text> — what you want to say; with --resolve, a one-line note on what you changed.
--artifact <id> — the id of the artifact to comment on; with --resolve, the artifact whose feedback listed the comment.
--on-session <id> — an agent session id of your own to comment on.
--reply-to <id> — the id of a comment to reply to.
--resolve <id> — the id of a comment you acted on, to resolve it with the text as its note.
--passage <text> — with --artifact: the exact text of whole lines of the artifact the comment is about.
--model <name> — your own model name, if you know it.
--json — print the raw response.
--token <token> — Mossbear API token — overrides the stored one for this call.
--dashboard-url <url> — override the dashboard base URL.

comments

Read the comments people have left about this repo’s context.

mossbear comments

--token <token> — dashboard API token (defaults to the stored one)
--dashboard <url> — dashboard URL override.
--since <cursor> — show comments changed after this cursor.

complete

Close the agent session for grading: upload what is left, and send this checkout’s locally-edited artifacts back. Installed as the session-end hook by mossbear init.

mossbear complete

--token <token> — Mossbear API token — overrides the stored token and is remembered in ~/.mossbear/config.json after a successful run.
--dashboard-url <url> — override the dashboard base URL for this call (default: ~/.mossbear/config.json then the baked-in default)
--transcripts-dir <path> — optional agent transcript directory (JSONL files)
--no-actions — upload permitted session data. --no-actions withholds actions, numerical usage, transcript excerpts and captured user turns. It does not stop complete sending back artifacts you edited under .mossbear/.
--dry-run — show session-sync JSON, including closing evidence and local usage-only counts. Nothing is sent or closed; the destination account is not verified and separate artifact uploads are excluded.
--no-prune — with --no-prune, keep delivered files a bundle no longer contains instead of removing them. By default delivery reconciles deletions, so an artifact deleted in the dashboard stops reaching agents through this repo; removals are always named, are skipped for a bundle whose pull failed or hit the artifact ceiling, and never touch a file carrying unsynced local edits.
--conflict <skip|local|remote> — how to resolve an artifact that changed both locally and on the server: ‘skip’ (default — leave it alone and report it), ‘local’ (send your copy), or ‘remote’ (overwrite your copy with the server’s). The default never prompts and never destroys either side, because these commands also run unattended from hooks.
--verbose — print the progress lines a successful run keeps to itself — what was extracted, uploaded and pulled. Errors, warnings, refusals, notes and anything that changed a file print either way.

Installed as the session-end hook. It closes the session so the dashboard can grade it, and sends back the artifacts edited under .mossbear/ in this checkout. When another agent session has been active in the same checkout it leaves those edits alone and says so, because nothing here can say which session is still writing them.

connect

Register Mossbear MCP in an agent without repeating repo setup. For Codex, run mossbear connect --platform codex. For Claude Code, run mossbear connect --platform claude_code.

mossbear connect --platform <agent>

--platform <agent> — agent to connect: codex or claude_code.
--scope <scope> — configuration scope; user is currently supported.
--replace — replace a conflicting user-scope Mossbear entry.

Registers mossbear mcp for every repo in the selected agent, using that agent’s installed CLI. A matching entry is kept. A conflicting or disabled entry is preserved unless you pass --replace; replacement removes the old entry before adding the new one. Unreadable configuration is never replaced. Restart the agent client afterward and check its MCP tools: this command checks registration, not an active connection.

doctor

Check your environment for common setup issues.

mossbear doctor

--verbose — print extra diagnostic output.
--dashboard-url <url> — override the dashboard base URL for the connection check (default: ~/.mossbear/config.json then the baked-in default)

Doctor checks the action-logging hook and the upload hook separately. Both failures look the same from the dashboard, which is no data, and they have opposite fixes. A project that logs but never uploads fills ~/.mossbear/runs/ and loses the lot on a container that is destroyed at session end.

guides

Generate and manage project guides.

Two subcommands. Both read the cache your last refresh wrote, with no network. What grading found about a guide is artifacts feedback.

active

List active guides for the current project.

mossbear guides active

No flags. This reads the cached bundle from your dashboard, not the files on disk, so it answers what the dashboard sent rather than what your agent will read. Guides with no file to be written back to are counted separately, because no refresh will ever put those on disk.

search

Search active guides by keyword.

mossbear guides search <query>

<query> — matched against each active guide’s title and content, case insensitively.

init

Set up mossbear: install the action logging hook and wire this repo.

mossbear init

--force — reset setup preferences and bundled skills, preserving privacy choices; ensure .agents/ exists.
--no-skill — skip writing the bundled skills to .claude/skills/ (Claude Code) and .agents/skills/ (Codex, OpenCode)
--skills-only — rewrite only the bundled skills, in each of .claude/skills/ and .agents/skills/ that already holds one (or, if neither does, the folder each --platform harness reads, .claude/skills/ by default), leaving other files and ~/.mossbear/config.json unchanged. Use this to clear skill drift after an upgrade.
--no-sync-hook — skip registering the Claude Code Stop hook that runs “mossbear report” after each assistant turn and uploads the actions the logger recorded.
--no-session-end-hook — skip registering the Claude Code SessionEnd hook that runs “mossbear complete”, tells the dashboard the session is over for grading, and sends this checkout’s locally edited artifacts back.
--no-session-start-hook — skip registering the Claude Code SessionStart hook that runs “mossbear refresh” before the first turn to deliver this repo’s subscribed artifacts.
--no-auto-update — skip installing the current Mossbear release before SessionStart refreshes. Running mossbear init with this option also removes the install step from an auto-updating entry it previously wrote.
--platform <list> — comma-separated harnesses to wire instead of detection: claude_code, codex, antigravity, opencode. Optional; omit for automatic selection.
--install-mcp / --no-install-mcp — explicitly install user-scope MCP registration, including without a terminal; --no-install-mcp skips the offer.
--mcp-scope <scope> — mCP configuration scope; user is currently supported.
--no-prompt — skip interactive questions, including the global rule discovery question.
--yes — ask nothing: same as --no-prompt. MCP registration is installed only with --install-mcp; otherwise its command is printed.
--pull-guides / --no-pull-guides — pull your guides from the dashboard into this repo without prompting (requires a token); --no-pull-guides never offers.
--ask-global / --no-ask-global — ask again whether guides scoped to every repo are delivered to this machine (needs a terminal)
--import-guides / --no-import-guides — import this repo’s existing guide files into the dashboard without prompting (requires a token); --no-import-guides never offers.
--dashboard-url <url> — dashboard base URL to persist in ~/.mossbear/config.json (default: prompt, fall back to https://app.mossbear.io)
--token <token> — optional dashboard API token to persist in ~/.mossbear/config.json — everything local works without one; needed only to sync with the dashboard (can also be set later via mossbear report --token)

The session-start hook it writes installs the current release and then runs mossbear refresh, so a session opens with this repo’s artifacts current and on a CLI that has the commands the other hooks name. --no-auto-update writes the refresh alone, and rewrites an auto-updating entry init wrote earlier.

link

Adopt this repo’s existing guide files (AGENTS.md, CLAUDE.md, .agents/, .claude/rules/, .cursorrules, .cursor/rules/) into your dashboard — with no arguments, pick from a list.

mossbear link [paths...]

[paths...] — files or folders to adopt. Omit to pick from everything adoptable in this repo.
--long — show each file’s description in the list instead of behind ”?N”.
--yes — take the default selection without prompting (required when stdin is not a TTY)
--copy-skills — copy each skill that is only in .claude/skills/ or only in .agents/skills/ into the other, so Claude Code and Codex both read it. Local only; adopts nothing.
--global — also scan ~/.claude/CLAUDE.md (overrides config default)
--no-global — skip ~/.claude/CLAUDE.md even when config.discoverGlobal is true.
--token <token> — Mossbear API token (overrides token in config)
--dashboard-url <url> — override the dashboard base URL for this call (default: ~/.mossbear/config.json then the baked-in default)
--cwd <path> — project root to scan (defaults to current working directory)

Connect this machine to your Mossbear account: prints a short code, you approve it in the browser, and the token is written to ~/.mossbear/config.json. The URL is always printed as well as opened, so you can still click or paste it if nothing comes up. Nothing is opened on a machine with no display, from a --print-url run, or when BROWSER=none is set.

mossbear login

--print-url — print the approval URL and code on their own lines and keep waiting, instead of assuming someone is at this terminal. Automatic when stdout is not a TTY.
--no-open — open the approval page in your browser. On by default at a terminal; use --no-open to just print it. Never happens with --print-url, or when stdout is not a TTY.
--dashboard-url <url> — dashboard to pair with. Defaults to the configured one.

If MOSSBEAR_TOKEN is set in your environment, login changes nothing and says so. The environment owns that credential and a config token written underneath it would be ignored on every later read, which would leave you looking at “paired” while every command kept using the old token.

mcp

Run the Mossbear MCP server over stdio, exposing your context layer (bundles + inbox) to any agent.

mossbear mcp

--token <token> — Mossbear API token — overrides the token stored in ~/.mossbear/config.json for this session.
--dashboard-url <url> — override the dashboard base URL (default: ~/.mossbear/config.json then the baked-in default)
--read-only — refuse context-layer writes (push/update/archive) regardless of config.
--bundles <slugs> — comma-separated allowlist of bundle slugs to expose, plus the special token @inbox to grant the personal inbox (default: config mcp.bundles, else all)

Human-facing messages go to stderr, because stdout is the JSON-RPC channel. See the context layer for the tools the server registers.

narration

Show or change whether this repo syncs redacted action excerpts and captured user turns.

mossbear narration [state]

[state] — on, off, or omitted to show the current setting.

The setting is keyed by a one-way digest of the repo, which is why it needs a command: you could not write the config key by hand. Off is exact rather than reduced. An opted-out repo’s actions are built with no narration field at all. If the opt-out list in your config is not a list of repo ids, narration is off everywhere until you fix it, and this command refuses to overwrite the malformed value.

promote

Make a Mossbear-owned artifact repository policy: write it into this repo’s working tree, uncommitted, for you to review and commit yourself.

mossbear promote [paths]

[paths] — repo-relative paths to promote, as the listing prints them. With none, this lists what is promotable and writes nothing.
--token <token> — Mossbear API token — overrides the stored token for this call.
--dashboard-url <url> — override the dashboard base URL for this call (default: ~/.mossbear/config.json then the baked-in default)
--dry-run — list what promoting the named paths would write and write none of them. Reads the same plan the real run does, so what it names is what you would get.
--yes — skip the question and write the named paths, for scripts. Without it a non-interactive run refuses rather than reading a newline as an answer. It never stands in for naming a path.

publish

Publish this repo’s declared artifacts from its published branch (default main) to the bundles it is the home of. Fetches that branch first; never reads your working copy or your checkout’s branch.

mossbear publish [paths]

[paths] — paths to add to published.paths in .mossbear/config.json. They publish once that change lands on the published branch.
--token <token> — Mossbear API token — overrides the stored token for this call.
--dashboard-url <url> — override the dashboard base URL for this call (default: ~/.mossbear/config.json then the baked-in default)
--no-fetch — skip fetching the published branch first, and publish what this clone already has of it.
--dry-run — show what this would publish and publish nothing. It reads the same plan the real run does, so what it names is what you would send.
--yes — skip the question and publish, for scripts and CI. Without it a non-interactive run refuses rather than reading a newline as an answer.
--replace-dashboard-copy <path> — publish the repo’s copy of these guides (comma-separated paths) over a dashboard edit no commit holds. At a terminal only, or with --yes.

pull

Pull a context bundle into this repo and subscribe so mossbear refresh keeps it fresh.

mossbear pull [bundle]

[bundle] — bundle to pull (omit for an interactive picker of your bundles)
--out <dir> — directory to export artifacts into (default: .mossbear/context/<bundle>/). Implies --once.
--once — export the bundle into its folder without subscribing — a one-off, not kept fresh by mossbear refresh.
--types <list> — comma-separated artifact types to include (guide,content,asset) — exports only, with --once or --out.
--query <text> — substring filter over artifact name + content — exports only, with --once or --out.
--limit <n> — max artifacts to export (default server-side: 100, max 500) — exports only, with --once or --out.
--account — subscribe your account rather than this repo — the bundle then reaches every checkout, and nothing is committed here.
--home — claim this repo as the bundle’s home: from then on its artifacts are published only from this repo’s published branch, and every other writer — including the dashboard — is refused.
--deliver <repo|global> — where this subscription’s artifacts land: repo (their path in the checkout) or global (your machine-wide skills). Omit to route each artifact on its own scope.
--token <token> — Mossbear API token — overrides the token stored in ~/.mossbear/config.json.
--dashboard-url <url> — override the dashboard base URL.

refresh

Refresh this repo’s Mossbear-owned artifacts before work begins. Installed as the session-start hook by mossbear init.

mossbear refresh

--token <token> — Mossbear API token — overrides the stored token and is remembered in ~/.mossbear/config.json after a successful run.
--dashboard-url <url> — override the dashboard base URL for this call (default: ~/.mossbear/config.json then the baked-in default)
--harness <harness> — identify the agent harness whose lifecycle report is supplied on stdin.
--no-prune — with --no-prune, keep delivered files a bundle no longer contains instead of removing them. By default delivery reconciles deletions, so an artifact deleted in the dashboard stops reaching agents through this repo; removals are always named, are skipped for a bundle whose pull failed or hit the artifact ceiling, and never touch a file carrying unsynced local edits.
--conflict <skip|local|remote> — how to resolve an artifact that changed both locally and on the server: ‘skip’ (default — leave it alone and report it), ‘local’ (send your copy), or ‘remote’ (overwrite your copy with the server’s). The default never prompts and never destroys either side, because these commands also run unattended from hooks.
--verbose — print the progress lines a successful run keeps to itself — what was extracted, uploaded and pulled. Errors, warnings, refusals, notes and anything that changed a file print either way.

mossbear init installs this as a SessionStart hook, behind the install clause, so a session opens with this repo’s Mossbear-owned artifacts current. It writes only Mossbear-managed locations: a path git delivers is refused and named, never overwritten.

report

Upload permitted session data, including usage-only token counts. Installed as the turn-stop hook by mossbear init.

mossbear report

--token <token> — Mossbear API token — overrides the stored token and is remembered in ~/.mossbear/config.json after a successful run.
--dashboard-url <url> — override the dashboard base URL for this call (default: ~/.mossbear/config.json then the baked-in default)
--transcripts-dir <path> — optional agent transcript directory (JSONL files)
--no-actions — upload permitted session data. --no-actions withholds actions, numerical usage, transcript excerpts and captured user turns. It does not stop complete sending back artifacts you edited under .mossbear/.
--dry-run — show session-sync JSON, including local usage-only counts. Nothing is sent; the destination account is not verified and separate artifact uploads are excluded.
--no-prune — with --no-prune, keep delivered files a bundle no longer contains instead of removing them. By default delivery reconciles deletions, so an artifact deleted in the dashboard stops reaching agents through this repo; removals are always named, are skipped for a bundle whose pull failed or hit the artifact ceiling, and never touch a file carrying unsynced local edits.
--conflict <skip|local|remote> — how to resolve an artifact that changed both locally and on the server: ‘skip’ (default — leave it alone and report it), ‘local’ (send your copy), or ‘remote’ (overwrite your copy with the server’s). The default never prompts and never destroys either side, because these commands also run unattended from hooks.
--verbose — print the progress lines a successful run keeps to itself — what was extracted, uploaded and pulled. Errors, warnings, refusals, notes and anything that changed a file print either way.

Installed as the turn-stop hook. It uploads permitted session data, including transcript-derived numerical counts for usage-only sessions. Local artifact edits are sent back by complete.

search

Search your guides, saved artifacts and past grading for a term (reads the dashboard).

mossbear search [term]

[term] — literal text, case-insensitive; * matches any run of characters and ? one character. Optional when --head-sha, --branch or --repo-id is given: then only your sessions are listed.
--corpus <guides,verdicts,content,comments,turns,sessions> — search only these corpora, comma-separated.
--author <person,agent,mossbear> — only comments written by these kinds of author, comma-separated (person, agent, mossbear)
--steering <correction,steering> — only your turns the classifier labelled so, comma-separated (correction, steering, new request, acknowledgement, insufficient evidence)
--subject <artifact,session> — only comments on these kinds of subject, comma-separated (artifact, session)
--head-sha <sha> — only your sessions that closed at exactly this commit (the full sha; a commit made mid-session matches nothing)
--branch <name> — only your sessions that closed on exactly this branch.
--repo-id <id> — only your sessions recorded under exactly this repo id.
--frontmatter <key=value> — only artifacts whose frontmatter has these fields, as key=value pairs separated by commas (type=recipe)
--limit <n> — hits shown per corpus.
--json — print the raw payload instead of a summary.
--token <token> — Mossbear API token — overrides the stored one for this call.
--dashboard-url <url> — override the dashboard base URL.

status

Show connected platforms, guide count, and pending syncs.

mossbear status

--verbose — list every file under each guidance directory.

Pending actions are the ones logged since the last successful upload, which is what report sends and what the dashboard grades. Status roots itself at the repo root, so running it from a subdirectory reports the same subscriptions refresh acts on. It reports only what is already declared and never mints a project id as a side effect of being run.

unlink

Stop delivering a guide file you linked — the file stays on disk and nothing about the guide is deleted.

mossbear unlink <paths...>

<paths...> — files or folders to stop grading. At least one is required.
--global — also scan ~/.claude/CLAUDE.md (overrides config default)
--no-global — skip ~/.claude/CLAUDE.md even when config.discoverGlobal is true.
--token <token> — Mossbear API token (overrides token in config)
--dashboard-url <url> — override the dashboard base URL for this call.
--cwd <path> — project root to scan (defaults to current working directory)

Unlink removes the membership link created, in the default bundle. A guide someone deliberately added to a curated bundle keeps arriving, and the command tells you which ones.

update

Update the mossbear CLI to the latest release.

mossbear update

--check — report whether an update is available without installing anything.
--yes — skip the confirmation prompt.
--refresh-assets — only bring generated files (the hook script) in step with this CLI version, then exit.

Running mossbear update is you asking, so it checks the registry even when the ambient nudge is switched off in config. If it cannot reach the registry it says so and exits non-zero, rather than claiming the CLI is current.

what-syncs

Show what leaves this machine when you sync, what stays on it, and the rules for transcript excerpts.

mossbear what-syncs