# tanomis session run

Reference for tanomis session run: invoke an agent: create a session, start a run, and stream its output.

Generated from the <code>tanomis</code> command tree on 2026-10-01. Flags and defaults match the binary; run <code>tanomis session run --help</code> for the version you have installed.

## Usage

```text title="Usage"
tanomis session run AGENT [flags]
```

## Description

Invoke an agent from the CLI. Creates a session for AGENT in the caller's tenant, starts a run, and streams the run's events to stdout, the same runtime path the Console drives (no shortcut). Useful for development and for producing runtime evidence (tool / egress ledger entries). Bound by the caller's token and tenant scope; grants no privilege the Console would not.

## Flags

| Flag | Type | Description |
|---|---|---|
| `--contract-ref` | string | What this work is judged against, set when the work is opened and never afterwards. |
| `--contract-version` | string | The revision of the contract named by `--contract-ref` (required with it). |
| `--file` | stringSlice | Upload and attach a local file (repeatable). |
| `--idempotency-key` | string | Replay the original run on retry instead of starting a new one. |
| `--input` | string | Raw JSON input object (mutually exclusive with `--prompt`). |
| `--model` | string | Model for the new session (bounded by the agent's permitted_models when model.invoke enforces). |
| `--no-stream` | bool | Start the run and print its id without streaming events. |
| `--no-wait` | bool | When a rule holds the run for approval, print the hold and exit instead of waiting for the answer. |
| `--objective` | string | What this work is for, in your words, shown to whoever reviews it (set when the work is opened). |
| `--prompt` | string | Prompt string sent as \{"prompt": ...\}. |
| `--session` | string | Post the run to an existing session instead of creating one (needed to release a hold a person approved on it). |
| `--work-id` | string | Continue an existing unit of work instead of opening a new one (mutually exclusive with `--work-subject`). |
| `--work-subject` | string | Declare the subject of the work this run serves (settlement-mode agents refuse to run without work). |

<details>
<summary>Global flags</summary>

| Flag | Type | Description |
|---|---|---|
| `--config` | string | Config file path. |
| `--context` | string | Config context to use. |
| `-o`, `--output` | string | Output format: table\|json. |
| `--tenant` | string | Tenant id (X-Tenant-ID). |
| `--verbose` | bool | Verbose output. |

</details>

## Examples