> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# mammoth agent

> All 45 mammoth agent commands with examples, arguments and confirmation flags: Work with Mammoth agent sessions, the changes a chat made, and its runs.

> Generated from mammoth-cli 2.4.2, released 2026-11-02: `mammoth schema list`, `mammoth capability list` and the CLI's own `--help`. Do not edit by hand; run `npm run docs:capabilities`.

Work with Mammoth agent sessions, the changes a chat made, and its runs. 45 commands. The `agent` group is hidden from `mammoth --help` until it is generally available, but every command runs; `mammoth agent --help` lists them.

Every command also takes the [global flags](https://mammoth.io/docs/build/cli/global-flags/) (`--output`, `--yes`, `--confirm`, `--dry-run`, `--input`, `--profile`, ...), which are not repeated below. `--input` takes a JSON or YAML document of the input fields; `mammoth schema get COMMAND_ID` prints a command's full input schema.

**Confirmation.** Commands marked `--yes --confirm TARGET` or `--yes` always need those flags, even at a terminal: they never prompt. Commands marked "`--yes` or prompt" ask at an interactive terminal (table output, no `--no-input`) and otherwise need `--yes`. `--dry-run` skips confirmation and sends nothing.

## Summary

| Command | What it does | Effect | Confirmation |
|---|---|---|---|
| [`agent chat`](#mammoth-agent-chat) | Send a chat message to an agent and wait for its reply. | Benign mutation | — |
| [`agent access askers`](#mammoth-agent-access-askers) | Count the people who can ask about a project without opening it. | Read | — |
| [`agent access chart save`](#mammoth-agent-access-chart-save) | Save the chart of an answer to the caller's own dashboard (Explore level). | Benign mutation | — |
| [`agent access grant give`](#mammoth-agent-access-grant-give) | Give people access to ask about projects. Managers only. | External effect | `--yes` |
| [`agent access grant list`](#mammoth-agent-access-grant-list) | List who can ask the agent about projects without opening the data. Managers only. | Read | — |
| [`agent access grant revoke`](#mammoth-agent-access-grant-revoke) | Revoke a person's access. Managers only. | Destructive | `--yes` or prompt |
| [`agent access grant update`](#mammoth-agent-access-grant-update) | Change a person's access. Managers only. | Benign mutation | — |
| [`agent access me`](#mammoth-agent-access-me) | What the agent may do for the caller in this workspace. | Read | — |
| [`agent access people`](#mammoth-agent-access-people) | List the workspace's members and what their own access gives their agent. | Read | — |
| [`agent access reach`](#mammoth-agent-access-reach) | List what one person's agent can see. | Read | — |
| [`agent access request add-to-context`](#mammoth-agent-access-request-add-to-context) | Keep a thumbs-down's correction in the project's agent context. Owners and admins. | Benign mutation | — |
| [`agent access request create`](#mammoth-agent-access-request-create) | Ask for access or a change, or flag an answer, from the chat. Any member. | Benign mutation | — |
| [`agent access request list`](#mammoth-agent-access-request-list) | List the workspace's agent requests. Owners and admins. | Read | — |
| [`agent access request mine`](#mammoth-agent-access-request-mine) | List the caller's own requests made from one chat. | Read | — |
| [`agent access request resolve`](#mammoth-agent-access-request-resolve) | Close a request. Owners, admins and the file's keeper. | Destructive | `--yes` or prompt |
| [`agent access settings get`](#mammoth-agent-access-settings-get) | Get the workspace's AI Agent controls. Managers only. | Read | — |
| [`agent access settings update`](#mammoth-agent-access-settings-update) | Change the workspace's AI Agent controls. Managers only. | High impact | `--yes --confirm TARGET` |
| [`agent access today`](#mammoth-agent-access-today) | Read the caller's Today page on the Ask home. | Read | — |
| [`agent access tree`](#mammoth-agent-access-tree) | List the projects and files the Give access tree offers. Managers only. | Read | — |
| [`agent action delete`](#mammoth-agent-action-delete) | Delete one object the chat created, by action id. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`agent action list`](#mammoth-agent-action-list) | List the changes one agent chat session made. | Read | — |
| [`agent message set-request-kind`](#mammoth-agent-message-set-request-kind) | Correct the request kind a reply answered. 'request_kind' comes from '--input'. | Benign mutation | — |
| [`agent plan approve`](#mammoth-agent-plan-approve) | Approve (Run it) the chat's current plan. Prompt or '--yes' required. | Benign mutation | `--yes` or prompt |
| [`agent plan discard`](#mammoth-agent-plan-discard) | Discard every proposed step of the chat's current plan. Prompt or '--yes' required. | Benign mutation | `--yes` or prompt |
| [`agent plan edit-proposal`](#mammoth-agent-plan-edit-proposal) | Rename or remove one item of a plan's waiting proposal; the fields come from '--input'. | Benign mutation | — |
| [`agent plan skip`](#mammoth-agent-plan-skip) | Skip one proposed step of the chat's current plan. | Benign mutation | — |
| [`agent run extend`](#mammoth-agent-run-extend) | Pause, resume, stop or extend one run; the SDK method is the manifest's. | Benign mutation | — |
| [`agent run instance list`](#mammoth-agent-run-instance-list) | List the agents of one run: the main agent, its workers and recon helpers. | Read | — |
| [`agent run instance messages`](#mammoth-agent-run-instance-messages) | List the messages one agent of a run sent or received. | Read | — |
| [`agent run instance transcript`](#mammoth-agent-run-instance-transcript) | Show the model messages of one agent of a run, credentials redacted. | Read | — |
| [`agent run list`](#mammoth-agent-run-list) | List the runs of one agent chat session. | Read | — |
| [`agent run pause`](#mammoth-agent-run-pause) | Pause, resume, stop or extend one run; the SDK method is the manifest's. | Benign mutation | — |
| [`agent run resume`](#mammoth-agent-run-resume) | Pause, resume, stop or extend one run; the SDK method is the manifest's. | Benign mutation | — |
| [`agent run retry`](#mammoth-agent-run-retry) | Retry one failed or stopped run as a new run; it starts paid model work. | Benign mutation | `--yes` or prompt |
| [`agent run status`](#mammoth-agent-run-status) | Show the current run of one agent chat session. | Read | — |
| [`agent run stop`](#mammoth-agent-run-stop) | Pause, resume, stop or extend one run; the SDK method is the manifest's. | Benign mutation | — |
| [`agent run units list`](#mammoth-agent-run-units-list) | List one page of the units a run's steps do; the filters come from '--input'. | Read | — |
| [`agent run units set`](#mammoth-agent-run-units-set) | Report the objects one plan step of a run will work on, as queued units. | Benign mutation | — |
| [`agent session delete`](#mammoth-agent-session-delete) | Delete one agent session by id. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`agent session feedback list`](#mammoth-agent-session-feedback-list) | List the ratings the creator gave one chat's replies. | Read | — |
| [`agent session list`](#mammoth-agent-session-list) | List agent sessions. All fields are optional and come from '--input'. | Read | — |
| [`agent session messages`](#mammoth-agent-session-messages) | Get the messages of one agent session by id. | Read | — |
| [`agent session set-visibility`](#mammoth-agent-session-set-visibility) | Set an agent session's visibility. 'visibility' comes from '--input'. | Benign mutation | — |
| [`agent turn cancel`](#mammoth-agent-turn-cancel) | Stop one turn of an agent chat session (the session's owner only). | Benign mutation | — |
| [`agent turn rate`](#mammoth-agent-turn-rate) | Rate one agent reply. Only the chat's creator may. | Benign mutation | — |

## agent commands

### mammoth agent chat

Send a chat message to an agent and wait for its reply.

```bash
mammoth agent chat --input '{"message": "Summarize revenue by region", "scope": {"type": "workspace", "workspace_id": 123}, "client_context": {"project_id": 456}}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `message` | `--input` field | yes | — | `str` |  |
| `scope` | `--input` field | yes | — | `dict[str, any]` |  |
| `agent_key` | `--input` field | no | — | `str` |  |
| `session_id` | `--input` field | no | — | `str` |  |
| `client_context` | `--input` field | no | — | `dict[str, any]` |  |
| `selection` | `--input` field | no | — | `dict[str, any]` |  |
| `wait` | `--input` field | no | — | `float` |  |
| `plan_ref` | `--input` field | no | — | `dict[str, any]` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Scope is {"type": "workspace", "workspace_id": N}, {"type": "user", "user_id": N} or {"type": "account"}. Put the project the question is about in client_context as {"project_id": N}. The command starts the turn and waits for the reply, up to 120 seconds: pass "wait": 0 to return at once with the turn id, or a larger "wait" for a long turn. If the wait ends first the result has working: true; read the finished reply with agent session messages SESSION_ID. The CLI sends one idempotency key per message and repeats it on a gateway error, so a retry never starts a second turn.
- **Id:** `agent.chat` · **Result:** `AgentChatResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.chat`, API `POST /agents/chat` (AgentChat)

## agent access

### mammoth agent access askers

Count the people who can ask about a project without opening it.

```bash
mammoth agent access askers 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `PROJECT_ID` | positional | yes | — | `int` | ID of the project whose askers to list. |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Needs a manager of the workspace's AI Agent settings, or someone who manages the project's people. Returns a count.
- **Id:** `agent.access.askers` · **Result:** `AgentAccessAskersResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_project_askers`, API `GET /agents/access/projects/{project_id}/askers` (GetAgentProjectAskers)

### mammoth agent access chart save

Save the chart of an answer to the caller's own dashboard (Explore level).

```bash
mammoth agent access chart save resource-123 resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the session. |
| `TURN_ID` | positional | yes | — | `str` | ID of the turn. |
| `dashboard_id` | `--input` field | no | — | `int` |  |
| `new_dashboard_name` | `--input` field | no | — | `str` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Required inputs: SESSION_ID, TURN_ID.
- **Id:** `agent.access.chart.save` · **Result:** `AgentAccessChartSaveResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_chart_save`, API `POST /agents/access/saved-charts` (SaveAgentChart)

### mammoth agent access grant give

Give people access to ask about projects. Managers only.

```bash
mammoth agent access grant give --input '{"emails": ["analyst@example.com"], "level": "ask", "items": [{"project_id": 1}]}' --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `emails` | `--input` field | yes | — | `list[str]` |  |
| `level` | `--input` field | yes | — | `str` |  |
| `items` | `--input` field | yes | — | `list[dict[str, any]]` |  |

- **Effect:** External effect, scope `profile` · **Confirmation:** always `--yes`, even at a terminal
- **Preconditions:** Only a manager of the workspace's AI Agent settings can give access. People outside the workspace are invited as free guests. Needs --yes. Read `agent access grant list` afterwards.
- **Id:** `agent.access.grant.give` · **Result:** `AgentAccessGrantGiveResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_grant_give`, API `POST /agents/access/grants` (GiveAgentAccess)

### mammoth agent access grant list

List who can ask the agent about projects without opening the data. Managers only.

```bash
mammoth agent access grant list
```

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Only a manager of the workspace's AI Agent settings can list grants.
- **Id:** `agent.access.grant.list` · **Result:** `AgentAccessGrantListResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_grants_list`, API `GET /agents/access/grants` (ListAgentGrants)

### mammoth agent access grant revoke

Revoke a person's access. Managers only.

```bash
mammoth agent access grant revoke 123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `GRANT_ID` | positional | yes | — | `int` | ID of the grant. |

- **Effect:** Destructive, scope `profile` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Only a manager of the workspace's AI Agent settings can revoke. Removes the grant at once; the person loses the access. Prompts, or pass --yes.
- **Id:** `agent.access.grant.revoke` · **Result:** `AgentAccessGrantRevokeResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_grant_revoke`, API `DELETE /agents/access/grants/{grant_id}` (RevokeAgentAccess)

### mammoth agent access grant update

Change a person's access. Managers only.

```bash
mammoth agent access grant update 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `GRANT_ID` | positional | yes | — | `int` | ID of the grant. |
| `level` | `--input` field | no | — | `str` |  |
| `items` | `--input` field | no | — | `list[dict[str, any]]` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Only a manager of the workspace's AI Agent settings can change a grant.
- **Id:** `agent.access.grant.update` · **Result:** `AgentAccessGrantUpdateResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_grant_update`, API `PATCH /agents/access/grants/{grant_id}` (ChangeAgentAccess)

### mammoth agent access me

What the agent may do for the caller in this workspace.

```bash
mammoth agent access me
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `preview_user_id` | `--input` field | no | — | `int` |  |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Id:** `agent.access.me` · **Result:** `AgentAccessMeResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_me`, API `GET /agents/access/me` (GetAgentAccessMe)

### mammoth agent access people

List the workspace's members and what their own access gives their agent.

```bash
mammoth agent access people
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `search` | `--input` field | no | — | `str` |  |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Only a manager of the workspace's AI Agent settings can list the people.
- **Id:** `agent.access.people` · **Result:** `AgentAccessPeopleResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_people`, API `GET /agents/access/people` (ListAgentPeople)

### mammoth agent access reach

List what one person's agent can see.

```bash
mammoth agent access reach
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `user_id` | `--input` field | no | — | `int` |  |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Anyone reads their own; another person's (user_id) is for managers of the AI Agent settings only.
- **Id:** `agent.access.reach` · **Result:** `AgentAccessReachResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_reach`, API `GET /agents/access/reach` (GetAgentAccessReach)

### mammoth agent access request add-to-context

Keep a thumbs-down's correction in the project's agent context. Owners and admins.

```bash
mammoth agent access request add-to-context 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `REQUEST_ID` | positional | yes | — | `int` | ID of the request. |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Required inputs: REQUEST_ID.
- **Id:** `agent.access.request.add-to-context` · **Result:** `AgentAccessRequestAddToContextResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_request_add_to_context`, API `POST /agents/access/requests/{request_id}/project-context` (AddAgentRequestToProjectContext)

### mammoth agent access request create

Ask for access or a change, or flag an answer, from the chat. Any member.

```bash
mammoth agent access request create --input '{"kind": "access", "text": "Please share the Sales project"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `kind` | `--input` field | yes | — | `str` |  |
| `text` | `--input` field | yes | — | `str` |  |
| `file_id` | `--input` field | no | — | `int` |  |
| `asked` | `--input` field | no | — | `str` |  |
| `session_id` | `--input` field | no | — | `str` |  |
| `turn_id` | `--input` field | no | — | `str` |  |
| `dashboard_id` | `--input` field | no | — | `int` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Id:** `agent.access.request.create` · **Result:** `AgentAccessRequestCreateResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_request_create`, API `POST /agents/access/requests` (CreateAgentAccessRequest)

### mammoth agent access request list

List the workspace's agent requests. Owners and admins.

```bash
mammoth agent access request list
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `status` | `--input` field | no | — | `str` |  |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Only a manager of the workspace's AI Agent settings can list everyone's requests; `agent access request mine` lists your own.
- **Id:** `agent.access.request.list` · **Result:** `AgentAccessRequestListResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_requests_list`, API `GET /agents/access/requests` (ListAgentAccessRequests)

### mammoth agent access request mine

List the caller's own requests made from one chat.

```bash
mammoth agent access request mine resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the session. |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Required inputs: SESSION_ID.
- **Id:** `agent.access.request.mine` · **Result:** `AgentAccessRequestMineResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_requests_mine`, API `GET /agents/access/requests/mine` (ListMyAgentAccessRequests)

### mammoth agent access request resolve

Close a request. Owners, admins and the file's keeper.

```bash
mammoth agent access request resolve 123 --input '{"status": "done"}' --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `REQUEST_ID` | positional | yes | — | `int` | ID of the request. |
| `status` | `--input` field | yes | — | `str` |  |

- **Effect:** Destructive, scope `profile` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Irreversible: a resolved request cannot be reopened, and the requester is told. status is done, declined or dismissed ('open' is refused). Prompts, or pass --yes.
- **Id:** `agent.access.request.resolve` · **Result:** `AgentAccessRequestResolveResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_request_resolve`, API `PATCH /agents/access/requests/{request_id}` (ResolveAgentAccessRequest)

### mammoth agent access settings get

Get the workspace's AI Agent controls. Managers only.

```bash
mammoth agent access settings get
```

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Only a manager of the workspace's AI Agent settings can read them.
- **Id:** `agent.access.settings.get` · **Result:** `AgentAccessSettingsGetResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_settings_get`, API `GET /agents/access/settings` (GetAgentSettings)

### mammoth agent access settings update

Change the workspace's AI Agent controls. Managers only.

```bash
mammoth agent access settings update --input '{"enabled": true}' --yes --confirm 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `enabled` | `--input` field | no | — | `bool` |  |
| `can_make_changes` | `--input` field | no | — | `bool` |  |
| `downloads` | `--input` field | no | — | `bool` |  |
| `viewers_explore` | `--input` field | no | — | `bool` |  |
| `managers` | `--input` field | no | — | `list[str]` |  |
| `role_exceptions` | `--input` field | no | — | `list[dict[str, any]]` |  |

- **Effect:** High impact, scope `profile` · **Confirmation:** always `--yes --confirm TARGET`, even at a terminal (TARGET is the exact id or name acted on; the `confirmation_required` error's hint names it)
- **Preconditions:** Only a manager of the workspace's AI Agent settings can change them. Changes the AI agent for the whole workspace, not one project; only the fields given change. Needs --yes and --confirm WORKSPACE_ID (the refusal prints the exact target). --dry-run reads the current settings and shows each field going from its current to its new value.
- **Id:** `agent.access.settings.update` · **Result:** `AgentAccessSettingsUpdateResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_settings_update`, API `PATCH /agents/access/settings` (UpdateAgentSettings)

### mammoth agent access today

Read the caller's Today page on the Ask home.

```bash
mammoth agent access today
```

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** The caller's Today page: its state, whether a newer page is being written, and its blocks.
- **Id:** `agent.access.today` · **Result:** `AgentAccessTodayResult`

### mammoth agent access tree

List the projects and files the Give access tree offers. Managers only.

```bash
mammoth agent access tree
```

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Only a manager of the workspace's AI Agent settings can read the tree.
- **Id:** `agent.access.tree` · **Result:** `AgentAccessTreeResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.access_tree`, API `GET /agents/access/tree` (GetAgentAccessTree)

## agent action

### mammoth agent action delete

Delete one object the chat created, by action id. Prompt or '--yes' required.

```bash
mammoth agent action delete resource-123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `ACTION_ID` | positional | yes | — | `str` | ID of the recorded action (from agent action list). |

- **Effect:** Destructive, scope `profile` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Writes. Deletes the object one recorded action made. The server deletes only an object the chat created (created=true in agent action list), refuses an object the chat only edited or that another object now uses, and re-checks your permission on it. The object goes to the trash, so it can be restored. Prompt or --yes. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.action.delete` · **Result:** `AgentActionDeleteResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.action_delete`, API `DELETE /agents/sessions/{session_id}/actions/{action_id}` (DeleteAgentSessionAction)

### mammoth agent action list

List the changes one agent chat session made.

```bash
mammoth agent action list
```

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Read-only. Lists every change the chat session made through the CLI (one row per write: action id, run and step, command, target object, whether the chat created the object, and its state after the write). Read it before agent action delete. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.action.list` · **Result:** `AgentActionListResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.action_list`, API `GET /agents/sessions/{session_id}/actions` (ListAgentSessionActions)

## agent message

### mammoth agent message set-request-kind

Correct the request kind a reply answered. 'request_kind' comes from '--input'.

```bash
mammoth agent message set-request-kind 'Summarize revenue by region' --input '{"request_kind": "ask"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `MESSAGE_ID` | positional | yes | — | `str` | ID of the reply message (from agent session messages). |
| `request_kind` | `--input` field | yes | — | `str` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Corrects the request kind a reply answered (ask, insight, build, automate or fix). Creator only. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.message.set-request-kind` · **Result:** `AgentMessageSetRequestKindResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.message_set_request_kind`, API `PATCH /agents/sessions/{session_id}/messages/{message_id}/request-kind` (CorrectAgentRequestKind)

## agent plan

### mammoth agent plan approve

Approve (Run it) the chat's current plan. Prompt or '--yes' required.

```bash
mammoth agent plan approve resource-123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the chat session (from agent session list). |
| `scope` | `--input` field | no | — | `dict[str, any]` |  |
| `wait` | `--input` field | no | — | `float` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Writes. This is the web app's Run it: it approves every proposed step of the chat's current plan and starts the work (paid model work). Typing 'Run it' as a chat message does not approve. The plan_id is read from the session; the request key is made by the CLI. Prompt or --yes. Waits up to wait seconds (default 120; wait 0 returns at once) for the turn. A user control: an embedded chat is refused. agent session messages shows when a chat waits for approval.
- **Id:** `agent.plan.approve` · **Result:** `AgentPlanApproveResult`

### mammoth agent plan discard

Discard every proposed step of the chat's current plan. Prompt or '--yes' required.

```bash
mammoth agent plan discard resource-123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the chat session (from agent session list). |
| `scope` | `--input` field | no | — | `dict[str, any]` |  |
| `wait` | `--input` field | no | — | `float` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Writes. Marks every proposed step of the chat's current plan skipped; it needs no model turn. The plan_id is read from the session. A user control: an embedded chat is refused.
- **Id:** `agent.plan.discard` · **Result:** `AgentPlanDiscardResult`

### mammoth agent plan edit-proposal

Rename or remove one item of a plan's waiting proposal; the fields come from '--input'.

```bash
mammoth agent plan edit-proposal --input '{"plan_id": "resource-123", "action": "rename", "key": "Status"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `plan_id` | `--input` field | yes | — | `str` |  |
| `action` | `--input` field | yes | — | `str` |  |
| `key` | `--input` field | yes | — | `str` |  |
| `name` | `--input` field | no | — | `str` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Renames or removes one item of the plan's waiting workflow proposal (action rename or remove, the item key, and name for a rename). Creator only. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.plan.edit-proposal` · **Result:** `AgentPlanEditProposalResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.plan_edit_proposal`, API `PATCH /agents/sessions/{session_id}/plan/proposal` (EditAgentPlanProposal)

### mammoth agent plan skip

Skip one proposed step of the chat's current plan.

```bash
mammoth agent plan skip resource-123 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the chat session (from agent session list). |
| `N` | positional | yes | — | `int` | Number of the proposed plan step to skip (from agent session messages). |
| `scope` | `--input` field | no | — | `dict[str, any]` |  |
| `wait` | `--input` field | no | — | `float` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Marks the proposed plan step N skipped; it needs no model turn. Only a proposed step can be skipped. The plan_id is read from the session. A user control: an embedded chat is refused.
- **Id:** `agent.plan.skip` · **Result:** `AgentPlanSkipResult`

## agent run

### mammoth agent run extend

Pause, resume, stop or extend one run; the SDK method is the manifest's.

```bash
mammoth agent run extend resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Gives a capped run a fresh time budget (the 8 hour active-time cap). The server refuses extend when this command runs from inside the run itself: a run cannot extend itself, ask the user to extend it. Returns the run after the request. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.extend` · **Result:** `AgentRunExtendResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_extend`, API `POST /agents/sessions/{session_id}/runs/{run_id}/extend` (ExtendAgentRun)

### mammoth agent run instance list

List the agents of one run: the main agent, its workers and recon helpers.

```bash
mammoth agent run instance list resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Read-only. Lists the agents of the run: the main agent, its workers and recon helpers, with the ids the instance commands take. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.instance.list` · **Result:** `AgentRunInstanceListResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_instances_list`, API `GET /agents/sessions/{session_id}/runs/{run_id}/instances` (ListAgentRunInstances)

### mammoth agent run instance messages

List the messages one agent of a run sent or received.

```bash
mammoth agent run instance messages resource-123 resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |
| `INSTANCE_ID` | positional | yes | — | `str` | ID of the agent (from agent run instance list). |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Read-only. The messages one agent of the run sent or received. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.instance.messages` · **Result:** `AgentRunInstanceMessagesResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_instance_messages`, API `GET /agents/sessions/{session_id}/runs/{run_id}/instances/{instance_id}/messages` (ListAgentInstanceMessages)

### mammoth agent run instance transcript

Show the model messages of one agent of a run, credentials redacted.

```bash
mammoth agent run instance transcript resource-123 resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |
| `INSTANCE_ID` | positional | yes | — | `str` | ID of the agent (from agent run instance list). |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Read-only. The model messages of one agent of the run, credentials redacted. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.instance.transcript` · **Result:** `AgentRunInstanceTranscriptResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_instance_transcript`, API `GET /agents/sessions/{session_id}/runs/{run_id}/instances/{instance_id}/transcript` (GetAgentInstanceTranscript)

### mammoth agent run list

List the runs of one agent chat session.

```bash
mammoth agent run list
```

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Read-only. Lists the runs of the chat session, newest first, with the same fields as agent run status. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.list` · **Result:** `AgentRunListResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_list`, API `GET /agents/sessions/{session_id}/runs` (ListAgentSessionRuns)

### mammoth agent run pause

Pause, resume, stop or extend one run; the SDK method is the manifest's.

```bash
mammoth agent run pause resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Pauses the run after its current call finishes; a waiting run pauses at once. Returns the run after the request. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.pause` · **Result:** `AgentRunPauseResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_pause`, API `POST /agents/sessions/{session_id}/runs/{run_id}/pause` (PauseAgentRun)

### mammoth agent run resume

Pause, resume, stop or extend one run; the SDK method is the manifest's.

```bash
mammoth agent run resume resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Resumes a paused run from where it stopped. The server refuses resume when this command runs from inside the run itself: a run cannot resume itself, ask the user to resume it. Returns the run after the request. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.resume` · **Result:** `AgentRunResumeResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_resume`, API `POST /agents/sessions/{session_id}/runs/{run_id}/resume` (ResumeAgentRun)

### mammoth agent run retry

Retry one failed or stopped run as a new run; it starts paid model work.

```bash
mammoth agent run retry resource-123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Writes. Retries a failed or stopped run as a new run, which starts paid model work. Session owner only. Prompt or --yes. Needs --session SESSION_ID; an embedded chat is refused.
- **Id:** `agent.run.retry` · **Result:** `AgentRunRetryResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_retry`, API `POST /agents/sessions/{session_id}/runs/{run_id}/retry` (RetryAgentRun)

### mammoth agent run status

Show the current run of one agent chat session.

```bash
mammoth agent run status
```

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Read-only. Shows the chat session's current durable run: run id, state (running, waiting, paused, capped, done, failed or stopped), the step it is on, what it waits for, and the active time used and left of its 8 hour budget (time spent waiting on you does not count). Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.status` · **Result:** `AgentRunStatusResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_status`, API `GET /agents/sessions/{session_id}/run` (GetAgentSessionRun)

### mammoth agent run stop

Pause, resume, stop or extend one run; the SDK method is the manifest's.

```bash
mammoth agent run stop resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Stops the run and cancels its live step. A stopped run cannot be resumed. Returns the run after the request. Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.stop` · **Result:** `AgentRunStopResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_stop`, API `POST /agents/sessions/{session_id}/runs/{run_id}/stop` (StopAgentRun)

### mammoth agent run units list

List one page of the units a run's steps do; the filters come from '--input'.

```bash
mammoth agent run units list resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |
| `step` | `--input` field | no | — | `int` |  |
| `state` | `--input` field | no | — | `str` |  |
| `cursor` | `--input` field | no | — | `int` |  |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Read-only. One page of the units the run's steps do, optionally only one step (step), one state (queued, running, done, failed or skipped) or from an offset (cursor). Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.run.units.list` · **Result:** `AgentRunUnitsListResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_units_list`, API `GET /agents/sessions/{session_id}/runs/{run_id}/units` (ListAgentRunUnits)

### mammoth agent run units set

Report the objects one plan step of a run will work on, as queued units.

```bash
mammoth agent run units set resource-123 --input '{"step": 1, "kind": "dataset", "units": [{"id": 12, "name": "Sales", "project_id": 3}]}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `RUN_ID` | positional | yes | — | `str` | ID of the run (from agent run status or agent run list). |
| `step` | `--input` field | yes | — | `int` |  |
| `kind` | `--input` field | yes | — | `str` |  |
| `units` | `--input` field | yes | — | `list[dict[str, any]]` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Reports once the objects a plan step will work on (kind is dataset, view and so on; 1 to 1000 units, each id with an optional name and project_id) so the run panel can list them and measure progress and the time left. A unit already listed is left as it is. Needs --session SESSION_ID; an embedded chat supplies it. The server, not the model, counts the units done and the time left.
- **Id:** `agent.run.units.set` · **Result:** `AgentRunUnitsSetResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.run_units_set`, API `POST /agents/sessions/{session_id}/runs/{run_id}/units` (RegisterAgentRunUnits)

## agent session

### mammoth agent session delete

Delete one agent session by id. Prompt or '--yes' required.

```bash
mammoth agent session delete resource-123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the session. |

- **Effect:** Destructive, scope `profile` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Required inputs: SESSION_ID.
- **Id:** `agent.session.delete` · **Result:** `AgentSessionDeleteResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.session_delete`, API `DELETE /agents/sessions/{session_id}` (DeleteAgentSession)

### mammoth agent session feedback list

List the ratings the creator gave one chat's replies.

```bash
mammoth agent session feedback list resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the session. |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Required inputs: SESSION_ID.
- **Id:** `agent.session.feedback.list` · **Result:** `AgentSessionFeedbackListResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.turn_feedback_list`, API `GET /agents/sessions/{session_id}/feedback` (ListAgentTurnFeedback)

### mammoth agent session list

List agent sessions. All fields are optional and come from '--input'.

```bash
mammoth agent session list
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `agent_key` | `--input` field | no | — | `str` |  |
| `limit` | `--input` field | no | — | `int` |  |
| `offset` | `--input` field | no | — | `int` |  |
| `include_shared` | `--input` field | no | — | `bool` |  |

- **Effect:** Read, scope `profile` · **Confirmation:** none · **Pages:** `single_page`
- **Id:** `agent.session.list` · **Result:** `AgentSessionListResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.session_list`, API `GET /agents/sessions` (ListAgentSessions)

### mammoth agent session messages

Get the messages of one agent session by id.

```bash
mammoth agent session messages resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the session. |

- **Effect:** Read, scope `profile` · **Confirmation:** none
- **Preconditions:** Required inputs: SESSION_ID.
- **Id:** `agent.session.messages` · **Result:** `AgentSessionMessagesResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.session_messages`, API `GET /agents/sessions/{session_id}/messages` (GetAgentSessionMessages)

### mammoth agent session set-visibility

Set an agent session's visibility. 'visibility' comes from '--input'.

```bash
mammoth agent session set-visibility resource-123 --input '{"visibility": "shared"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the session. |
| `visibility` | `--input` field | yes | — | `str` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Required inputs: SESSION_ID.
- **Id:** `agent.session.set-visibility` · **Result:** `AgentSessionSetVisibilityResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.session_set_visibility`, API `PATCH /agents/sessions/{session_id}` (SetAgentSessionVisibility)

## agent turn

### mammoth agent turn cancel

Stop one turn of an agent chat session (the session's owner only).

```bash
mammoth agent turn cancel resource-123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `TURN_ID` | positional | yes | — | `str` | ID of the turn to stop (from the chat's events or agent session messages). |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Writes. Stops one turn of the chat session: no further model or tool call starts, the call running is cut, and the turn ends with a stopped event that lists the writes already made. Only the session's owner may; a repeat, or a call after the turn ended, answers the turn's state (stopping, stopped or ended). Needs --session SESSION_ID; an embedded chat supplies it.
- **Id:** `agent.turn.cancel` · **Result:** `AgentTurnCancelResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.turn_cancel`, API `POST /agents/sessions/{session_id}/turns/{turn_id}/cancel` (CancelAgentTurn)

### mammoth agent turn rate

Rate one agent reply. Only the chat's creator may.

```bash
mammoth agent turn rate resource-123 resource-123 --input '{"rating": "up"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SESSION_ID` | positional | yes | — | `str` | ID of the session. |
| `TURN_ID` | positional | yes | — | `str` | ID of the turn. |
| `rating` | `--input` field | yes | — | `str` |  |
| `comment` | `--input` field | no | — | `str` |  |

- **Effect:** Benign mutation, scope `profile` · **Confirmation:** none
- **Preconditions:** Required inputs: SESSION_ID, TURN_ID.
- **Id:** `agent.turn.rate` · **Result:** `AgentTurnRateResult` · **Backed by:** SDK `mammoth.api.agents.AgentsAPI.turn_rate`, API `POST /agents/sessions/{session_id}/turns/{turn_id}/feedback` (RateAgentTurn)

---
Source: https://mammoth.io/docs/build/cli/agent.md · Updated: 2026-11-02
