The Motir CLI

Before you start

A Motir account, and Node >=22. That is the list. You do not need a checkout of Motir itself, and you do not need to mint a token by hand — step 2 signs you in from the terminal.

1Install

Motir ships as a global npm package. pnpm add -g and yarn global add install the same thing. Runtime: Node >=22, ESM.

npm install -g @motir/cli
motir --help

2Sign in

motir login prints a short code, opens Motir in your browser, and waits for you to approve it there. Nothing has to exist on this machine first — no token to mint, no file to create.

motir login

3Link your workspace root

Your workspace root is the folder your repo checkouts live under — a Motir project usually spans several repositories, and the work loop runs across all of them. Linking that folder writes a .motir.json there, and every command finds it by walking upward, so any command works from inside any checkout.

cd ~/work                  # the folder holding your checkouts
motir link --project ACME

If your workspace has exactly one project, motir link on its own is the whole step. .motir.json holds no secret — server, workspace, project — so it is safe to commit. Linking also brings the code down: it reads the project’s repositories and clones the ones that are missing, one reported line each, never writing into a path that already exists. Run it again any time — nothing already there is re-cloned, and a repository added to the project later arrives. Pass --no-clone to bind and nothing else. An empty folder is first class: bind it and the code is there. The one thing binding cannot fetch is a repository that does not exist anywhere yet — that is what a scaffold work item creates.

4Check it

One read-only pass that answers *is my setup correct?* before a dispatch stops halfway through — your credential, the link, the project, your agent binary and its own sign-in.

motir doctor

It exits non-zero when a hard check fails, so motir doctor && motir auto is a usable gate, and --json emits the same report machine-readably. It never reads your secret: the credential checks ask only whether a path exists or an env var is set.

5See what is ready

Get your bearings before you pick anything up: where the project stands, what the current sprint holds, and what can actually start right now.

motir status      # ready / in-flight counts + the active sprint
motir sprint      # the active sprint, and what blocks what
motir ready       # what can be picked up right now

motir sprint and motir ready print dependency edges in their own columns, so you can see which item unblocks the most before choosing one.

6Dispatch one item

Read the card first. motir show gives you the whole thing — its fields, its readiness, its dependency edges and, for a story, its children in build order. That is where you notice the item assumes something that does not exist yet.

motir show MOTIR-42       # the item you are about to hand an agent
motir next --print        # claim the top item, print its prompt

--print writes the prompt to stdout and everything else — the repo, the resolved path, the workflow mode — to stderr, so motir next --print | pbcopy copies the prompt alone while you still see the context. Paste it into whatever agent you like. When its pull request is merged, close the item out:

motir done --via in_review MOTIR-42

Where Motir keeps things

Motir keeps exactly two files, and only one of them holds a secret.

The CLI talks to https://app.motir.co unless you tell it otherwise. Self-hosting? --server <url> beats everything on any command, and motir help environment prints the whole resolution ladder from the shipped code.

Every command

Derived from the CLI’s own command record, so a command the tool gains appears here with no edit to this page. Run motir help <command> for its flags.

What next

You have a working CLI and one item dispatched. Three places to go from here, and each owns something this page deliberately does not.