CLI reference
Use this when you are looking up the exact behavior of a spor verb: its
flags, aliases, and which mode it runs in.
You do not need this if you came to complete a task rather than look up a verb; start with Common CLI tasks, or use Start here for first-time setup.
After reading this, you should be able to find a verb’s entry, read its
mode badge, and check the installed version’s own help with
spor help <command>.
The spor command line is the shell surface for the graph. One binary
serves both modes: local, where the graph is a git repository of
markdown files on your machine, and remote, where your team shares one
graph on the Spor server. Each verb resolves local-versus-remote per call,
so scripts and habits carry over when a personal graph grows into a team
one. This reference documents the binary’s own help; spor help <command>
is always the word on the version you have installed.
If you came to do something specific rather than look up a verb, start with Common CLI tasks: short recipes that link into the verb entries here.
Installing the package also gives you a second, much smaller binary:
spor-hook, the dispatcher wired hosts call automatically, plus the
doctor diagnostic meant to be run by hand. It has its own entry: the
spor-hook reference.
Mode badges
Section titled “Mode badges”Every verb on the following pages carries one of three badges:
- local — runs entirely against files on your machine; no server is involved. Includes machine and repo configuration verbs.
- remote — needs a team server. In local mode these verbs degrade with a one-line explanation rather than an error.
- dual — works in both modes, resolving per call: local mode reads and writes the graph home on disk, remote mode calls the server, and output is designed to match across modes.
Mode is set by configuration: SPOR_SERVER in the environment (or the
equivalent config key) resolves to remote, unset means local against
$SPOR_HOME. spor status reports what resolved and why. The full cascade,
the .spor/.spor.json repo markers, and the credential store are on the
Configuration page.
Command groups
Section titled “Command groups”| Page | Verbs |
|---|---|
| Setup and identity | init, install, upgrade, status, join, auth, login, migrate, whoami, person, token |
| Team administration | invite, admin |
| Reading the graph | next, get, query, blame, history, changes, analytics, schema, lens, share, export |
| Writing to the graph | add, ask, drain, put-node, edge, set-status, priority, ready, correct, claim, renew, extend, release, run |
| Repo scoping | enable, disable, link, agents-md, compile, brief, validate |
| Dispatch | agent, dispatch, runs, repos, capabilities |
| Utilities | cost, version, help |
All verbs, A to Z
Section titled “All verbs, A to Z”| Verb | Mode | Alias | What it does |
|---|---|---|---|
| add | dual | capture |
capture a node from prose |
| admin | remote | gardener sweep and team token admin | |
| agent | dual | person-owned automation identities and their standing tokens | |
| agents-md | local | agents |
write or refresh the committed AGENTS.md graph-upkeep directive |
| analytics | dual | created-vs-completed work metrics | |
| ask | dual | question |
file a question the graph can’t answer |
| auth | remote | sign in and manage org-scoped credentials | |
| blame | dual | commits |
which nodes reference a commit |
| brief | dual | compile a briefing for a node | |
| capabilities | dual | caps, profiles |
this machine’s dispatch capability map |
| changes | dual | recent graph activity feed | |
| claim | remote | take the heartbeat-renewed lease on a task | |
| compile | dual | full neighborhood or prompt-time digest | |
| correct | dual | propose-correction |
record a standing briefing correction |
| cost | local | LLM spend summary | |
| disable | local | turn Spor off for this repo | |
| dispatch | dual | bg |
compile a briefing and launch a background agent |
| drain | remote | sync |
flush spooled captures to the team server |
| edge | dual | add-edge |
add a typed edge from a node |
| enable | local | opt this repo in | |
| export | dual | the nodes tarball, history bundle, or restore backup | |
| extend | remote | extend your live claim by a duration | |
| get | dual | one node by id | |
| help | local | the verb list, or a command’s detailed help | |
| history | dual | a node’s commit lineage | |
| init | local | create the local graph home | |
| install | local | setup |
wire spor into an agent |
| invite | remote | mint a teammate token (admin) | |
| join | remote | add an org-scoped credential from a pasted token | |
| lens | remote | render-lens |
render a saved view |
| link | local | set this repo’s canonical repo slug | |
| login | remote | interactive sign-in (alias of auth login) |
|
| migrate | local | push |
push the local graph to a git remote you own |
| next | dual | queue |
the ranked decision queue |
| person | local | create or list local person nodes | |
| priority | dual | set-priority |
set a queue item’s human-triage priority |
| put-node | dual | write a full node markdown file | |
| query | dual | filterable node and edge enumeration | |
| ready | dual | stamp or clear a node’s agent-readiness override | |
| release | remote | hand a task back to the pool | |
| renew | remote | heartbeat your live claim | |
| repos | dual | the dispatch slug map and repo-identity tags | |
| run | remote | start or inspect a workflow run | |
| runs | local | what happened to the runs this machine dispatched | |
| schema | dual | introspect the live schema registry | |
| set-status | dual | status-set |
set a node’s status, claiming on active |
| share | remote | mint a shareable read-only view link | |
| status | dual | resolved mode, graph, project, identity, health | |
| token | remote | self-serve personal access tokens | |
| upgrade | local | update |
refresh wired spor to the installed version |
| validate | local | lint the local graph | |
| version | local | print the package version | |
| whoami | remote | who the team graph thinks you are |