@remits/remits-cli 0.1.133 → 0.1.136

package/skills/remits-cli/references/tool-reference.md

@@ -72,8 +72,8 @@ For long-running Action/Agent runners, use the tool's own async mode (`execution
 the `actionRunId`/`agentRunId` (and, for agents, `sessionId`) immediately:
 
 ```bash
-remits-cli tool --name "mcp_run_action" --input '{"accountId":37,"actionName":"Rebuild Invoice","executionMode":"async","actionInput":{"invoiceId":"abc"}}' --data-mode prod
-# poll by run id:  {"controlAction":"status","accountId":37,"actionRunId":"<actionRunId>"}
+remits-cli tool --account-id 21 --as-account 37 --target-account 37 --name mcp_run_action --input '{"actionName":"Rebuild Invoice","executionMode":"async","actionRunId":"my-stable-run-id","actionInput":{"invoiceId":"abc"}}' --data-mode prod
+# poll by run id:  --account-id 21 --as-account 37 --target-account 37 --input '{"controlAction":"status","actionRunId":"my-stable-run-id"}'
 ```
 
 For long tools that lack their own async mode, use the CLI transport async (`--async true`), optionally with
@@ -81,13 +81,24 @@ For long tools that lack their own async mode, use the CLI transport async (`--a
 (see `command-reference.md` → *Tool Execution Lifecycle*). Use `--timeout-ms <ms>` only to adjust the per-request client timeout; it is
 not a replacement for async mode on multi-minute workflows.
 
-**Account-id precedence for tool calls.** When the CLI and the tool input both carry an account id, the server resolves them in this order:
+**Account roles for tool calls.** Keep the repo/scope account separate from the account whose data/runtime the
+tool exercises:
 
-1. Explicit `--account-id <ID>` flag — always wins. Use this when you want to be certain the tool runs against a specific account (and the user's session covers it).
-2. `input.accountId` (or `input.account_id`) — the tool's per-call execution target.
-3. The current repo's `account-info.json` / active session — the default fallback.
+1. `--account-id <ID>` is the repo/scope account that bounds discovery and verification.
+2. `--as-account <ID>` is the execution account, matching `test run --as-account`.
+3. `--target-account <ID>` is the tool/data target when the tool operates on a specific account but should not
+   change component resolution. It is sent as `input.accountId` and `input.targetAccountId` when `--input`
+   omits them — `input.accountId` is the key `mcp_run_action` and friends actually read, and without it they
+   fall back to the run scope.
 
-So from inside a parent account's repo you can target a child account just by setting `input.accountId`, or force it with `--account-id` if you need it to override whatever the tool input says. Verify with the `accountId` field in the response envelope.
+A target does not move the run: pass `--as-account` too whenever the work should resolve as that account's
+components, branch subscription and staging lane.
+
+Legacy `input.accountId` (or `input.account_id`) is still accepted as an explicit target for older snippets,
+but prefer flags for new work; the CLI warns on stderr and in `warnings[]` when it is used alone. The
+response `world` block is the source of truth: check `repoAccountId`, `executionAccountId`,
+`targetAccountId`, `componentBranch`, `workspace`, and `dataMode`. `world.accountId` is the execution
+account.
 
 ### `mcp_account_view`
 Returns complete account structure — schemas, components, relationships.
@@ -414,7 +425,7 @@ staged-vs-DB provenance in the result.
 Describe the Action first when the input shape is not obvious. This does not execute the Action:
 
 ```bash
-remits-cli tool --name mcp_run_action --input '{"controlAction":"describe","accountId":743,"actionId":25,"includeInputSchema":true}' --data-mode prod
+remits-cli tool --account-id 21 --as-account 49 --target-account 49 --name mcp_run_action --input '{"controlAction":"describe","actionId":25,"includeInputSchema":true}' --data-mode prod
 ```
 
 The describe response reports `hasInputSchema`, optional `inputSchema`, `inferredInputKeys`, and component
@@ -423,7 +434,7 @@ provenance. If `hasInputSchema:false`, treat `inferredInputKeys` as a best-effor
 Use direct mode only for quick Actions:
 
 ```bash
-remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"direct","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+remits-cli tool --account-id 21 --as-account 49 --target-account 49 --name mcp_run_action --input '{"actionId":200,"executionMode":"direct","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
 ```
 
 Use the tool's own async mode for long-running Action execution — it returns immediately with an
@@ -432,14 +443,14 @@ of the start response. Do **not** also pass the CLI `--async` flag; that only bu
 transport layer:
 
 ```bash
-remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"async","actionRunId":"my-stable-run-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+remits-cli tool --account-id 21 --as-account 49 --target-account 49 --name mcp_run_action --input '{"actionId":200,"executionMode":"async","actionRunId":"my-stable-run-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
 ```
 
 Then poll that run with another **regular tool call** carrying `controlAction:"status"` and the same
-`accountId` + `actionRunId`:
+explicit account flags + `actionRunId`:
 
 ```bash
-remits-cli tool --name mcp_run_action --input '{"controlAction":"status","accountId":49,"actionRunId":"my-stable-run-id"}' --data-mode prod
+remits-cli tool --account-id 21 --as-account 49 --target-account 49 --name mcp_run_action --input '{"controlAction":"status","actionRunId":"my-stable-run-id"}' --data-mode prod
 ```
 
 > This poll is a normal `remits-cli tool --name mcp_run_action` call — **not** `remits-cli tool status`,
@@ -448,12 +459,17 @@ remits-cli tool --name mcp_run_action --input '{"controlAction":"status","accoun
 > If you started the run with a different `userId`, include that same `userId` in the poll (the run's status
 > is keyed by account + user + `actionRunId`; it otherwise defaults to the current user).
 
+`input.accountId` is still accepted by older tool implementations and legacy snippets, but it is no longer
+the recommended way to describe cross-account work. Prefer `--account-id` for the repo/scope account and
+`--as-account`/`--target-account` for the Action's execution/data account so verification packets and
+`activity inspect --scope related` can report the split world without guessing.
+
 For job-style Actions only (`Action.job == true`), prefer `executionMode:"event"` when you want the durable
 Event lifecycle, Event status, and platform recovery behavior. Event mode is inherently async; poll it the
 same way (`controlAction:"status"` + `actionRunId`) — the status resolves the backing Event's terminal state:
 
 ```bash
-remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"event","actionRunId":"my-stable-run-id","actionInput":{}}' --data-mode prod
+remits-cli tool --account-id 21 --as-account 49 --target-account 49 --name mcp_run_action --input '{"actionId":200,"executionMode":"event","actionRunId":"my-stable-run-id","actionInput":{}}' --data-mode prod
 ```
 
 Returned fields on the async/event start: `actionRunId`, `status:"running"`, `executionMode`,
@@ -482,10 +498,10 @@ turns up a run that is consuming resources and should not finish — the case th
 
 ```bash
 # the usual path: you found the event in mcp_record_listing / mcp_object_activity
-remits-cli tool --name mcp_run_action --data-mode prod --input '{"controlAction":"interrupt","accountId":49,"eventId":19102,"reason":"runaway extraction, 45min"}'
+remits-cli tool --account-id 21 --as-account 49 --target-account 49 --name mcp_run_action --data-mode prod --input '{"controlAction":"interrupt","eventId":19102,"reason":"runaway extraction, 45min"}'
 
 # or stop a run you started yourself (executionMode:'event' only)
-remits-cli tool --name mcp_run_action --data-mode prod --input '{"controlAction":"interrupt","accountId":4,"actionRunId":"my-run-id"}'
+remits-cli tool --account-id 21 --as-account 49 --target-account 49 --name mcp_run_action --data-mode prod --input '{"controlAction":"interrupt","actionRunId":"my-run-id"}'
 ```
 
 Aliases `cancel` / `stop` / `kill` all work. What you need to know before using it: