Skip to content

cayu session

Generated from the released command parser. These commands show help only; operations run when you invoke the command without --help.

Terminal window
usage: cayu session [-h]
                    {list,show,interactions,usage,tools,events,transcript,resolve-provider-operation} ...


Inspect durable Cayu sessions without mutating storage, or send an explicit
provider-operation disposition to a running Cayu server. Start with `cayu
session list`; JSON is the default output.


positional arguments:
  {list,show,interactions,usage,tools,events,transcript,resolve-provider-operation}
    list                List sessions by newest activity.
    show                Show a compact session overview.
    interactions        Page response-scoped interaction summaries.
    usage               Show per-model-call token usage.
    tools               Show paired durable tool calls.
    events              Page durable session events.
    transcript          Page bounded transcript metadata and previews.
    resolve-provider-operation
                        Explicitly retry or fail unavailable provider work.


options:
  -h, --help            show this help message and exit

cayu session list

Section titled “cayu session list”
Terminal window
usage: cayu session list [-h] [--sqlite PATH | --postgres DSN]
                         [--status {pending,running,interrupting,completed,failed,interrupted}]
                         [--agent AGENT] [--environment ENVIRONMENT]
                         [--label KEY=VALUE] [--limit LIMIT]
                         [--offset OFFSET | --cursor CURSOR]
                         [--format {json,table,jsonl} | --json | --table |
                         --jsonl] [--output FILE]


List sessions by newest activity. Use a returned session id with `cayu session
show SESSION_ID`.


options:
  -h, --help            show this help message and exit
  --sqlite PATH
  --postgres DSN
  --status {pending,running,interrupting,completed,failed,interrupted}
  --agent AGENT         Filter by exact agent name.
  --environment ENVIRONMENT
                        Filter by exact environment name.
  --label KEY=VALUE     Filter by an exact label; repeat for multiple labels.
  --limit LIMIT
  --offset OFFSET
  --cursor CURSOR
  --format {json,table,jsonl}
                        Output format (default: json).
  --json                Emit JSON (shorthand for `--format json`).
  --table               Emit human-readable output (shorthand for `--format
                        table`).
  --jsonl               Emit JSON Lines (shorthand for `--format jsonl`).
  --output, -o FILE     Write output to FILE instead of stdout.

cayu session show

Section titled “cayu session show”
Terminal window
usage: cayu session show [-h] [--sqlite PATH | --postgres DSN]
                         [--format {json,table,jsonl} | --json | --table |
                         --jsonl] [--output FILE]
                         session_id


Show a compact session overview. Use usage, tools, events, or transcript for
bounded detail.


positional arguments:
  session_id


options:
  -h, --help            show this help message and exit
  --sqlite PATH
  --postgres DSN
  --format {json,table,jsonl}
                        Output format (default: json).
  --json                Emit JSON (shorthand for `--format json`).
  --table               Emit human-readable output (shorthand for `--format
                        table`).
  --jsonl               Emit JSON Lines (shorthand for `--format jsonl`).
  --output, -o FILE     Write output to FILE instead of stdout.

cayu session interactions

Section titled “cayu session interactions”
Terminal window
usage: cayu session interactions [-h] [--sqlite PATH | --postgres DSN]
                                 [--before-sequence BEFORE_SEQUENCE]
                                 [--limit LIMIT]
                                 [--format {json,table,jsonl} | --json |
                                 --table | --jsonl] [--output FILE]
                                 session_id


Page durable interaction summaries newest first. Use an interaction id with
usage, tools, events, or transcript for response-scoped evidence.


positional arguments:
  session_id


options:
  -h, --help            show this help message and exit
  --sqlite PATH
  --postgres DSN
  --before-sequence BEFORE_SEQUENCE
  --limit LIMIT
  --format {json,table,jsonl}
                        Output format (default: json).
  --json                Emit JSON (shorthand for `--format json`).
  --table               Emit human-readable output (shorthand for `--format
                        table`).
  --jsonl               Emit JSON Lines (shorthand for `--format jsonl`).
  --output, -o FILE     Write output to FILE instead of stdout.

cayu session usage

Section titled “cayu session usage”
Terminal window
usage: cayu session usage [-h] [--sqlite PATH | --postgres DSN]
                          [--offset OFFSET] [--limit LIMIT]
                          [--after-sequence AFTER_SEQUENCE]
                          [--before-sequence BEFORE_SEQUENCE]
                          [--interaction-id INTERACTION_ID]
                          [--format {json,table,jsonl} | --json | --table |
                          --jsonl] [--output FILE]
                          session_id


Show bounded per-model-call token usage and pricing state. Use `--limit` and
`--offset` to page results.


positional arguments:
  session_id


options:
  -h, --help            show this help message and exit
  --sqlite PATH
  --postgres DSN
  --offset OFFSET
  --limit LIMIT
  --after-sequence AFTER_SEQUENCE
  --before-sequence BEFORE_SEQUENCE
  --interaction-id INTERACTION_ID
  --format {json,table,jsonl}
                        Output format (default: json).
  --json                Emit JSON (shorthand for `--format json`).
  --table               Emit human-readable output (shorthand for `--format
                        table`).
  --jsonl               Emit JSON Lines (shorthand for `--format jsonl`).
  --output, -o FILE     Write output to FILE instead of stdout.

cayu session tools

Section titled “cayu session tools”
Terminal window
usage: cayu session tools [-h] [--sqlite PATH | --postgres DSN]
                          [--offset OFFSET] [--limit LIMIT]
                          [--after-sequence AFTER_SEQUENCE]
                          [--before-sequence BEFORE_SEQUENCE]
                          [--interaction-id INTERACTION_ID]
                          [--format {json,table,jsonl} | --json | --table |
                          --jsonl] [--output FILE]
                          session_id


Show paired durable tool calls without result bodies. Use event inspection for
bounded payload metadata.


positional arguments:
  session_id


options:
  -h, --help            show this help message and exit
  --sqlite PATH
  --postgres DSN
  --offset OFFSET
  --limit LIMIT
  --after-sequence AFTER_SEQUENCE
  --before-sequence BEFORE_SEQUENCE
  --interaction-id INTERACTION_ID
  --format {json,table,jsonl}
                        Output format (default: json).
  --json                Emit JSON (shorthand for `--format json`).
  --table               Emit human-readable output (shorthand for `--format
                        table`).
  --jsonl               Emit JSON Lines (shorthand for `--format jsonl`).
  --output, -o FILE     Write output to FILE instead of stdout.

cayu session events

Section titled “cayu session events”
Terminal window
usage: cayu session events [-h] [--sqlite PATH | --postgres DSN]
                           [--type EVENT_TYPES] [--tool TOOL] [--agent AGENT]
                           [--environment ENVIRONMENT] [--since SINCE]
                           [--until UNTIL] [--after-sequence AFTER_SEQUENCE]
                           [--before-sequence BEFORE_SEQUENCE]
                           [--interaction-id INTERACTION_ID] [--limit LIMIT]
                           [--include-payload [BYTES]]
                           [--format {json,table,jsonl} | --json | --table |
                           --jsonl] [--output FILE]
                           session_id


Page durable session events with optional filters. Use `--include-payload`
only for bounded payload previews.


positional arguments:
  session_id


options:
  -h, --help            show this help message and exit
  --sqlite PATH
  --postgres DSN
  --type EVENT_TYPES
  --tool TOOL
  --agent AGENT
  --environment ENVIRONMENT
  --since SINCE
  --until UNTIL
  --after-sequence AFTER_SEQUENCE
  --before-sequence BEFORE_SEQUENCE
  --interaction-id INTERACTION_ID
  --limit LIMIT
  --include-payload [BYTES]
  --format {json,table,jsonl}
                        Output format (default: json).
  --json                Emit JSON (shorthand for `--format json`).
  --table               Emit human-readable output (shorthand for `--format
                        table`).
  --jsonl               Emit JSON Lines (shorthand for `--format jsonl`).
  --output, -o FILE     Write output to FILE instead of stdout.

cayu session transcript

Section titled “cayu session transcript”
Terminal window
usage: cayu session transcript [-h] [--sqlite PATH | --postgres DSN]
                               [--offset OFFSET] [--limit LIMIT]
                               [--interaction-id INTERACTION_ID] [--sizes]
                               [--include-content [BYTES]]
                               [--format {json,table,jsonl} | --json |
                               --table | --jsonl] [--output FILE]
                               session_id


Page bounded transcript metadata with redacted content by default. Use
`--include-content` only for bounded, redacted previews.


positional arguments:
  session_id


options:
  -h, --help            show this help message and exit
  --sqlite PATH
  --postgres DSN
  --offset OFFSET
  --limit LIMIT
  --interaction-id INTERACTION_ID
  --sizes               Include serialized size metadata for each content
                        part.
  --include-content [BYTES]
                        Include redacted serialized content, bounded per
                        message.
  --format {json,table,jsonl}
                        Output format (default: json).
  --json                Emit JSON (shorthand for `--format json`).
  --table               Emit human-readable output (shorthand for `--format
                        table`).
  --jsonl               Emit JSON Lines (shorthand for `--format jsonl`).
  --output, -o FILE     Write output to FILE instead of stdout.

cayu session resolve-provider-operation

Section titled “cayu session resolve-provider-operation”
Terminal window
usage: cayu session resolve-provider-operation [-h] --stage-id STAGE_ID
                                               --run-epoch RUN_EPOCH
                                               --action {fallback_retry,fail}
                                               [--reason REASON]
                                               [--metadata JSON]
                                               --server-url SERVER_URL
                                               [--authorization-env NAME]
                                               [--mutation-id MUTATION_ID]
                                               [--format {json,table} |
                                               --json | --table]
                                               [--output FILE]
                                               session_id


Send a run-epoch-fenced fallback_retry or fail disposition to the Cayu server.
Read stage_id and run_epoch from `cayu session show` or the session state API.
Authorization is read from CAYU_API_AUTHORIZATION by default and is never
printed.


positional arguments:
  session_id


options:
  -h, --help            show this help message and exit
  --stage-id STAGE_ID
  --run-epoch RUN_EPOCH
  --action {fallback_retry,fail}
  --reason REASON
  --metadata JSON       Bounded JSON object recorded with the durable
                        resolution.
  --server-url SERVER_URL
                        Cayu server root URL, including any mount prefix but
                        excluding /api.
  --authorization-env NAME
                        Environment variable containing the complete
                        Authorization header value.
  --mutation-id MUTATION_ID
                        Stable Cayu-Mutation-ID for correlating an ambiguous
                        SSE reconnect.
  --format {json,table}
                        Output format (default: json).
  --json                Emit JSON (shorthand for `--format json`).
  --table               Emit human-readable output (shorthand for `--format
                        table`).
  --output, -o FILE     Write output to FILE instead of stdout.
Section titled “Related guides”

Getting started · Operations · Configuration