Skip to content

CLI

npm i -g @meshpoint/cli
meshpoint --version

Node 22 or newer. The binary must be on PATH; hooks call it by name.

meshpoint login [--base-url <url>] [--agent <name>] [--org <id>] [--device | --browser]
meshpoint login --base-url <url> --token <token>
meshpoint logout
meshpoint whoami
meshpoint status
meshpoint doctor [--json]
meshpoint --version
meshpoint connect [--json]
meshpoint connect <harness> [--project <dir>] [--remove]
meshpoint connect pi [--pi-dir <dir>]
meshpoint connect opencode [--config-dir <dir>]
meshpoint items put --item <kind> <title> <body> [--item ...]
meshpoint items put --file <path>
meshpoint items put < items.json
meshpoint items retract <id>...
meshpoint org
meshpoint org invite <email> [--role <role>]
meshpoint org role <user-id> <role>
meshpoint org invites
meshpoint org remove <user-id>
meshpoint org sessions
meshpoint org revoke <session-id>
meshpoint org rotate-key [--revoke-sessions]
meshpoint org projects
meshpoint tap claude-code | codex | cursor | antigravity [<event>] | openclaw

Signs in and stores a session in ~/.config/meshpoint/config.json (mode 600). With a browser available it opens <api>/v1/auth/start, listens on a random 127.0.0.1 port, and receives a one-time grant after sign-in. Without one (no DISPLAY or WAYLAND_DISPLAY on Linux, an SSH or CI shell) it requests a device code, prints the URL and the 8-character code, and polls until you approve at app.meshpoint.dev/device. The code expires after 15 minutes. --device and --browser force one flow; denial and expiry exit 1.

  • --agent <name>: the session’s agent name, default cli-<hostname>. Shown to teammates as presence.
  • --org <id>: which organization to sign into when you belong to several.
  • --base-url <url>: another platform origin. Default https://api.meshpoint.dev.
  • --token <token>: store a pasted agent token instead of signing in.

The stored token lives 7 days and is refreshed by every command when under a day is left, using a 90-day refresh secret. A failed refresh keeps the stored token.

whoami prints the account, organization and role. status prints the config path and the project id and branch for the current directory, or says why the directory is not a project.

Checks, in order: the login file exists; the token is accepted (GET /v1/me); the current directory is a git repository with an origin remote; every harness found on the machine is connected at user scope or for this repository; the project’s last capture; the spool directory is writable. Lines marked · are informational (no capture yet). Lines marked ✗ fail the command with exit 1. --json returns {ok, checks: [{id, status, detail}]}.

See Connect a harness. Without a name, lists the harnesses found on this machine with their connection state and the command for each; --json for agents.

put writes items for the current repository and branch and records the checkpoint time. Three input forms: repeated --item kind title body, --file <path> with a JSON array of {kind, title, body}, or the same array on stdin. Kinds: decision, gotcha, convention, fact, status, todo. Prints {"count", "project", "branch"}.

retract takes ids or unique id prefixes, resolved against a fresh recall of the branch; an ambiguous prefix is refused. Prints {"retracted": [...]}.

Role requirements are in Teams and organizations. org alone prints the organization, members and key ids.

The hook entry point. Reads one event payload on stdin and prints the hook’s answer. Installed hooks call it; you do not. Every failure degrades to an empty answer so the harness is never broken.

Path What
~/.config/meshpoint/config.json login: base URL, token, refresh secret, org, agent name (mode 600)
~/.local/state/meshpoint/spool/<session>.jsonl turns waiting to be sent
~/.local/state/meshpoint/checkpoints/<project>--<branch>.json time of the last checkpoint
~/.local/state/meshpoint/nudges/<session>.json time of the last nudge
~/.local/state/meshpoint/antigravity/, openclaw-replies/ per-harness bookkeeping

XDG_CONFIG_HOME and XDG_STATE_HOME are honoured.

0 success, 1 a check or command failed (doctor, login denied or expired), 2 usage error (unknown command prints the usage text).