跳至主要內容
Motir
免費開始

CLI

@motir/cli · 版本 0.15.0 · 32 個指令

Motir CLI 與託管代理程式所用的是同一個 MCP 伺服器。它基於限定在某個工作區的權杖，把規劃與執行的迴圈自動化：一次執行會領取下一個就緒的工作項目，取得伺服器產生的提示，並在沙箱中排程一個代理程式去執行它。工作項目是事實記錄的來源；CLI 只是驅動者。

安裝

Node >=22。可以全域安裝，也可以不安裝、直接執行一次。

install

npm install -g @motir/cli

# or, without installing:
npx @motir/cli --help

認證

裝置流程是最短的路徑：它會顯示一個程式碼，開啟 Motir，並等待核准。如果已經有個人存取權杖，也可以直接交給 CLI。無論哪種方式，除非另行指定，CLI 都會連線到 https://app.motir.co。

authenticate

motir login

# or with a token you already hold:
motir auth login --server https://app.motir.co --token <pat>

# or from the environment:
export MOTIR_SERVER=https://app.motir.co
export MOTIR_TOKEN=<pat>

接著把一個資料夾繫結到專案，並在首次執行前檢查設定。

link and check

motir link --project ACME
motir doctor

指令

CLI 註冊的每一條指令，按 motir help 輸出的順序排列，由二進位檔自身宣告的目錄產生——因此這份清單不會落後於釋出版本。它描述的是 @motir/cli@0.15.0。

下方的指令和選項說明是已安裝的 motir 指令輸出的文字，因此保持英文。

SETUP COMMANDS:

  • motir login

    Connect this terminal: shows a code, opens Motir, waits for your approval.

    --server <url>
    Server base URL, e.g. https://app.motir.co
    --no-browser
    Do not launch a browser — just print the code and the URL to open anywhere.
  • motir logout

    Disconnect this terminal: remove the stored token for a server.

    --server <url>
    Server to log out of (defaults to the linked / single server).
  • motir auth

    Authenticate to a Motir server with a PAT.

  • motir auth login

    Validate and store a personal access token for a server.

    --server <url>
    Server base URL, e.g. https://app.motir.co
    --token <pat>
    Personal access token (or set MOTIR_TOKEN; prompted if omitted).
  • motir auth status

    Show the resolved server, token prefix, and owning user.

    --server <url>
    Server to report (defaults to the linked / single server).
  • motir auth logout

    Remove the stored token for a server.

    --server <url>
    Server to log out of (defaults to the linked / single server).
  • motir link

    Bind this workspace-root folder to a project, and clone the repositories it is missing.

    --server <url>
    Server base URL (defaults to the existing link / single server).
    --workspace <slug>
    Workspace slug (defaults to the token’s active workspace).
    --project <key>
    Project key, e.g. ACME. Omit it and the workspace’s only project is used.
    --repo <name>
    Mark THIS directory as a single repo’s checkout (writes a "." override).
    --no-clone
    Bind only — do not clone the project’s missing checkouts.
  • motir link add <repo> <path>

    Add a repo checkout-path override (relative to the link root, or absolute).

  • motir link remove <repo>

    Remove a repo checkout-path override.

  • motir doctor

    Preflight your BYOK setup: auth, project link, agent binary, credential presence.

    --agent <cmd>
    Check THIS agent command instead of the configured one.
    --json
    Emit the check results as JSON.

READ COMMANDS:

  • motir ready

    List the linked project’s ready leaves, grouped under their runnable containers — or, with --parent / --bug, the other two ready lanes.

    --kinds <list>
    Comma-separated kinds: epic,story,task,bug,subtask.
    --parent
    List the runnable containers — what `motir next --parent` runs.
    --bug
    List the ready bugs instead of the leaves.
    --assignee <id>
    Filter by assignee: a user id, "me", or "unassigned".
    --json
    Emit the ready items as JSON.
  • motir status

    Show the project pulse: ready / in-flight counts + the active sprint.

    --json
    Emit the pulse as JSON.
  • motir sprints

    List the project’s sprints: state, item count, points, window.

    --state <state>
    Only sprints in this state: planned, active, or complete.
    --json
    Emit the sprint rows as JSON.
  • motir sprint [ref]

    List ONE sprint’s work items (defaults to the active sprint).

    --kinds <list>
    Comma-separated kinds: epic,story,task,bug,subtask.
    --json
    Emit the sprint and its items as JSON.
  • motir show <key>

    Read one work item (e.g. ACME-7): fields, readiness, children, edges, body.

    --json
    Emit the get_work_item payload as JSON.
    --activity
    Also print the activity stream: comments and history, one page.
    --comments
    Also print the comment threads only, one page.
  • motir open <key>

    Open a work item (e.g. ACME-7) in the browser; prints the URL.

    --print
    Print the URL only; do not launch a browser.

WORK LOOP COMMANDS:

  • motir next

    Dispatch the next ready leaf (never a bug): claim it and deliver its prompt. --parent runs the next runnable container; --bug takes the next bug.

    --kinds <list>
    Comma-separated kinds: epic,story,task,bug,subtask.
    --parent
    Run the next runnable container (a story, task or bug whose children are all leaves) as a parent run — as `motir run <KEY>` would.
    --bug
    Take the next ready bug instead of the next leaf.
    --print
    Print the prompt to stdout INSTEAD of launching an agent (default). Not --print-prompt.
    --print-prompt
    ALSO echo the assembled prompt to stderr as it is sent, and still run the agent.
    --agent <cmd>
    Run THIS agent command on the prompt (overrides MOTIR_AGENT).
    --reset
    Clear this project’s session exclude list before picking.
    --disable-log-bug
    Do not let the agent file a bug for a defect it finds elsewhere; it comments instead.
    --disable-replan
    Do not let the agent submit a re-plan for a wrong work item; it comments and stops.
    --auto-approve-replan
    Not supported — approving a submitted re-plan and continuing is a `motir auto` flag.
    --report-log
    ALSO send your agent’s output to Motir, so a failed run shows its tail on the run page. OFF by default — only the lifecycle is sent, never file contents, paths or diffs.
  • motir run <scope>

    Run a scope: one work item, a whole story, or `sprint` for the active one.

    --print
    Print the prompt to stdout INSTEAD of launching an agent (default). One item; not --print-prompt.
    --print-prompt
    Echo each assembled prompt to stderr as it is sent, alongside the run (2> prompts.log).
    --agent <cmd>
    Run THIS agent command on the prompt (overrides MOTIR_AGENT).
    --force
    Dispatch even though the item is not ready (dependencies unmet). One work item only.
    --allow-soft-block
    Run an item held only by an ancestor's block (a SOFT block). Still refuses one with its own open blocker (a HARD block — only --force passes that).
    --disable-log-bug
    Do not let the agent file a bug for a defect it finds elsewhere; it comments instead.
    --disable-replan
    Do not let the agent submit a re-plan for a wrong work item; it comments and stops.
    --auto-approve-replan
    Not supported — approving a submitted re-plan and continuing is a `motir auto` flag.
    --max <n>
    Stop after dispatching n work items from the scope.
    --keep-going
    Continue past a failed agent instead of halting on the first one.
    --include-planning
    Trigger an AI expansion for an unexpanded story instead of refusing it. Never waits: the plan needs your approval.
    --kinds <list>
    Not supported — a scoped run drains the whole claimed set, not a filtered subset.
    --report-log
    ALSO send your agent’s output to Motir, so a failed run shows its tail on the run page. OFF by default — only the lifecycle is sent, never file contents, paths or diffs.
    --run-id <id>
    Adopt a run Motir already opened (a hosted run) instead of opening one. Env: MOTIR_DISPATCH_RUN_ID.
  • motir fix <key>

    Hand a work item whose pull requests are failing, whose merge could not land because of its code, or whose acceptance video was sent back to re-run, to your agent, on their own branches.

    --agent <cmd>
    Run THIS agent command on the fix (overrides MOTIR_AGENT).
    --report-log
    ALSO send your agent’s output to Motir, so a failed run shows its tail on the run page. OFF by default — only the lifecycle is sent, never file contents, paths or diffs.
  • motir continue <key>

    Carry on a work item whose last run died, on the branch it left — from any machine, without starting it over.

    --agent <cmd>
    Run THIS agent command on the continue (overrides MOTIR_AGENT).
    --max <n>
    A parent: stop after dispatching n more work items.
    --keep-going
    A parent: continue past a failed agent instead of halting.
    --report-log
    ALSO send your agent’s output to Motir, so a failed run shows its tail on the run page. OFF by default — only the lifecycle is sent, never file contents, paths or diffs.
  • motir review <key>

    Hosted only: review a work item’s pull requests at the version under review and submit ONE verdict — never pushes, never posts to GitHub.

  • motir auto

    Drain the ready set unattended: one item at a time onto a session branch.

    --agent <cmd>
    Run THIS agent command on every prompt (overrides MOTIR_AGENT).
    --kinds <list>
    Comma-separated kinds: epic,story,task,bug,subtask.
    --max <n>
    Stop after dispatching n work items.
    --keep-going
    Continue past a failed agent instead of halting on the first one.
    --reset
    Clear this project’s session exclude list before starting.
    --include-planning
    Trigger an AI expansion for each unexpanded epic/story instead of skipping it. Never waits: the plan needs your approval.
    --print
    Not supported — an unattended loop has nobody to paste a prompt. --print-prompt IS.
    --print-prompt
    Echo each assembled prompt to stderr as it is sent, alongside the run (2> prompts.log).
    --disable-log-bug
    Do not let the agent file a bug for a defect it finds elsewhere; it comments instead.
    --disable-replan
    Do not let the agent submit a re-plan for a wrong work item; it comments and stops.
    --auto-approve-replan
    Approve a re-plan the agent submitted and keep looping, instead of stopping for you.
    --report-log
    ALSO send your agent’s output to Motir, so a failed run shows its tail on the run page. OFF by default — only the lifecycle is sent, never file contents, paths or diffs.
  • motir batch

    Implement a FROZEN snapshot of the ready set: one pull request per item.

    --agent <cmd>
    Run THIS agent command on every prompt (overrides MOTIR_AGENT).
    --kinds <list>
    Comma-separated kinds: epic,story,task,bug,subtask.
    --max <n>
    Stop after dispatching n work items.
    --keep-going
    Continue past a failed agent instead of halting on the first one.
    --reset
    Clear this project’s session exclude list before snapshotting.
    --print
    Not supported — a frozen snapshot has nobody to paste a prompt. --print-prompt IS.
    --print-prompt
    Echo each assembled prompt to stderr as it is sent, alongside the run (2> prompts.log).
    --disable-log-bug
    Do not let the agent file a bug for a defect it finds elsewhere; it comments instead.
    --disable-replan
    Do not let the agent submit a re-plan for a wrong work item; it comments and stops.
    --auto-approve-replan
    Not supported — approving a submitted re-plan and continuing is a `motir auto` flag.
    --report-log
    ALSO send your agent’s output to Motir, so a failed run shows its tail on the run page. OFF by default — only the lifecycle is sent, never file contents, paths or diffs.
  • motir plan [args...]

    Plan by talking: resume the project’s planning conversation, add turns, submit.

    --detach
    Submit and return with the job/plan ids; do not wait for the planner.
  • motir done [key]

    Close out a merged item — or a whole merged session branch.

    --session <branch>
    Bulk close-out: flip every item on this session branch.
    --via <status>
    Move through this status first (e.g. in_review).

ADDITIONAL COMMANDS:

  • motir agent-terminal

    The terminal server inside a Motir agent image.

  • motir agent-terminal serve

    Serve this agent’s shell to Motir’s relay over WebSocket.

    --port <port>
    Port to listen on, on every interface (default 7681).
  • motir agent-terminal run <key>

    Open a run session for a card in this agent’s terminal server, and return its id at once.

    --run-id <id>
    The run to open a session for (its credentials are read on stdin).
    --command <command>
    What the session is for: run (the default), fix or continue.
  • motir agent-terminal stop

    Stop a run’s session: SIGTERM, then SIGKILL after 10 seconds.

    --run-id <id>
    The run whose session to stop.
  • motir agent-terminal status

    Report whether a run’s session is running, or how it exited.

    --run-id <id>
    The run whose session to report.
  • motir agent-terminal signin

    Print whether this agent’s coding agent is signed in, as JSON.

    --json
    Print JSON (the only format; accepted for scripts that ask for it).

HELP TOPICS:

  • motir help [command...]

    Show help for a command, or read a help topic.

Motir 把檔案儲存在哪裡

共三個檔案，其中只有一個儲存機密——而它並不是位於你的儲存庫裡的那個。下面每個路徑都可以改到別處；motir help files 會根據實際安裝的二進位檔輸出它們，並給出用來移動各個檔案的變數。

  • ~/.config/motir/config.json ——機密，切勿提交 憑證儲存：個人存取權杖唯一會寫入的檔案，檔案權限經 chmod 600 設定，所在目錄權限為 0700，並以伺服器 URL 為鍵，因此一台機器可以儲存多個 Motir 伺服器的權杖。你設定的代理程式指令也儲存在這裡。可透過 MOTIR_CONFIG_HOME 或 XDG_CONFIG_HOME 改變它的位置。
  • .motir.json ——不含機密，可以放心提交 位於工作區根目錄的專案連結：記錄這個資料夾所繫結的伺服器、工作區和專案，另有一份可選的儲存庫覆蓋對應。它不含任何憑證，因此應當納入版本控制。每條指令都會從目前目錄向上逐級查詢它，所以在根目錄下任何一個儲存庫副本內都可以執行任意指令。
  • ~/.local/state/motir/session-excludes.json ——不含機密 工作階段排除清單：記錄排程失敗的工作項目，這樣下一次執行會跳過它們，而不是再次選中同一個失敗項。它屬於狀態而非憑證，所以不與權杖放在一起——沙箱會以唯讀方式掛載設定目錄，而執行絕不能因為寫不進這個檔案而中止。如果它不可寫，Motir 只會警告一次，然後繼續。可透過 MOTIR_STATE_HOME 改變它的位置。

執行在哪裡進行

排程的代理程式在一個容器內執行，容器裡有你的儲存庫副本和你自己的代理程式憑證——容器提供什麼、它的權杖拒絕什麼，以及首次執行會遇到的故障，都在 沙箱 頁面，這裡不再重複。不使用 CLI 而把代理程式串接 Motir，見 MCP 伺服器；透過 HTTP 驅動同一個工作迴圈，見 API 參考。完整的指令參考——三種執行形態、工作階段分支、失敗策略與故障排查——是 motir-core 中的 docs/cli.md。