CLI reference

Command overview

Every invocation resolves to exactly one command. The argument-free invocation is dual-mode — the server when its output is piped, the help screen in a terminal — so an agent and a human both get the right thing.

Anything else is rejected: the binary prints ryvem-mcp: unknown command … to stderr and exits with status 1.

Running the server

With no arguments and stdout connected to a pipe — the way every MCP client launches it — ryvem-mcp starts the JSON-RPC server over stdio. The same command in an interactive terminal prints the help screen instead, so you never get a silent, seemingly-hung process. Registration with a client is covered in Getting started.

On connect it writes a single status line to stderr, reporting the loaded profiles and where the memory graph lives:

ryvem-mcp connected (stdio) — profiles: company, personal (default: company) — memory graph: ~/.ryvem/dev.db

help

Prints the version banner and the full command list grouped into Usage, Config, and Server. The bare invocation in a terminal shows the same screen.

ryvem-mcp help

--version

Prints the running version, then makes a best-effort check for a newer release against the official download host (RYVEM_BASE_URL overrides it, e.g. for a mirror). The check is entirely optional: an unreachable host prints a friendly note and never fails the command.

ryvem-mcp --version

update

Self-updates the binary in place. It downloads this platform's asset and the SHA256SUMS manifest from the official host (or RYVEM_BASE_URL when set), verifies the SHA-256 digest, and atomically replaces the running executable. A checksum mismatch aborts the install — a partial or tampered download is never written over your binary.

ryvem-mcp update        # confirm the replacement interactively
ryvem-mcp update --yes  # skip the confirmation (also -y)

On a terminal it asks Replace the running binary? before writing; --yes (or -y) proceeds unattended, for scripts and CI. The asset it fetches is chosen from your platform and architecture:

setup

The interactive wizard that writes a named profile into the global store at ~/.ryvem/config.json — the same file the installer configures on first run, and the friendly front end to the config commands below. Run it any time to add another account or update an existing one; each run writes atomically, so a crash never leaves the store half-written.

ryvem-mcp setup

It asks, in order:

Each token prompt shows where to create it, the name to give it (ryvem-mcp), and the exact scopes — the same values tabulated in Providers and Getting started. When it finishes, the wizard prints where it wrote, which profile is now the default, and the next step: bind a repo with ryvem-mcp use <name>.

use

Binds the repository you are in to a profile by name, or — with no argument — reports how the repo resolves. It only ever writes the profile name; the file it touches, ryvem.json at the repo root, stays secret-free and committable.

ryvem-mcp use company   # bind this repo to the "company" profile
ryvem-mcp use           # print this repo's resolution, write nothing

doctor

A read-only self-diagnosis. It makes no network calls, changes nothing, and always exits 0 — safe to run any time, and the first thing to reach for when a board will not connect or a repo resolves the wrong account. It reports the environment it sees and flags common problems in plain words.

ryvem-mcp doctor

A healthy machine prints something like this — every secret masked to its last four characters, every URL reduced to its host:

ryvem-mcp doctor

version       0.4.2
executable    /home/you/.local/bin/ryvem-mcp
data dir      ~/.ryvem

.env          ~/.local/bin/.env  (found)
  RYVEM_PROVIDER   jira
  JIRA_URL         yourco.atlassian.net
  JIRA_EMAIL       you@company.com
  JIRA_TOKEN       set (…a1b4)
  GITHUB_TOKEN     set (…9f2c)

config.json   ~/.ryvem/config.json  (found)
  profiles         company, personal
  default          company

this repo     /home/you/code/app/ryvem.json
  profile          company
  repoId           repo:6f1e2a9c-…
  resolves to      company   (board: jira)

No problems found.

Section by section, it prints the version and process.execPath; the data directory; the .env path it checked and whether it exists, followed by the board-relevant variables that are present by name with masked values (URLs as their host, emails shown, tokens as set (…abcd)); the config.json path, whether it exists, the profile names, and the default; and the cwd repo's ryvem.json — its profile and repoId, or that it is absent — with the profile and board provider that resolve.

In place of No problems found, it names anything it can see is wrong:

config

The config family is the scriptable, non-interactive front end to the global profile store at ~/.ryvem/config.json — the same store setup writes through a wizard. A profile bundles one board with the version-control and knowledge accounts that belong to the same context. This section is the command reference; the file format and every field's meaning live in Configuration.

Flags

Keys for config set

set and unset accept only these dotted keys; a typo is rejected rather than silently stored.

Example

Create a Jira profile, fill in its board and a GitHub token, and make it the default:

ryvem-mcp config add company --provider jira
ryvem-mcp config set company board.url https://yourco.atlassian.net
ryvem-mcp config set company board.email you@company.com
ryvem-mcp config set company board.token <api-token>
ryvem-mcp config set company github.token <github-token>
ryvem-mcp config default company
ryvem-mcp config show company

graph export

Renders the current memory graph to a single self-contained, interactive HTML file — no server, no external assets — and prints the absolute path of what it wrote to stdout. It opens the store read-only and skips the boot-time migration, so it stays fast and side-effect-free. The graph itself is described in Memory graph.

ryvem-mcp graph export
ryvem-mcp graph export --out ./graph.html --open
ryvem-mcp graph export --scope global