CLI
npm i -g @meshpoint/climeshpoint --versionNode 22 or newer. The binary must be on PATH; hooks call it by name.
Commands
Section titled “Commands”meshpoint login [--base-url <url>] [--agent <name>] [--org <id>] [--device | --browser]meshpoint login --base-url <url> --token <token>meshpoint logoutmeshpoint whoamimeshpoint statusmeshpoint 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.jsonmeshpoint items retract <id>...
meshpoint orgmeshpoint org invite <email> [--role <role>]meshpoint org role <user-id> <role>meshpoint org invitesmeshpoint org remove <user-id>meshpoint org sessionsmeshpoint org revoke <session-id>meshpoint org rotate-key [--revoke-sessions]meshpoint org projects
meshpoint tap claude-code | codex | cursor | antigravity [<event>] | openclawSigns 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, defaultcli-<hostname>. Shown to teammates as presence.--org <id>: which organization to sign into when you belong to several.--base-url <url>: another platform origin. Defaulthttps://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, status
Section titled “whoami, status”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.
doctor
Section titled “doctor”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}]}.
connect
Section titled “connect”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.
Exit codes
Section titled “Exit codes”0 success, 1 a check or command failed (doctor, login denied or expired), 2 usage error (unknown command prints the usage text).
