everruns sessions

Running and archived sessions, their state and participants.

Command	What it does
sessions create	Create a new session.
sessions watch	Watch session events in real time.
sessions export	Export session messages as JSONL or an ATIF trajectory.
sessions archive	Archive a session so it drops out of default lists.
sessions cancel	Cancel the currently executing turn in a session.
sessions delete	Delete a session.
sessions fork	Fork a session into a new, independent session that copies its conversation history and workspace files.
sessions get	Get session details including status, agent, harness, and model.
sessions context	Get the latest estimated context token breakdown for a session, grouped by system prompt, tools, rules, skills, MCP, subagents, and conversation.
sessions facets	Counts per status, source, and agent plus masthead metrics for the sessions list, over the same filters as list_sessions.
sessions stats	Get session counts by status.
sessions list	List sessions.
sessions pin	Pin a session for the current user.
sessions resume	Resume all paused session budgets for a session.
sessions unarchive	Restore an archived session to default lists.
sessions unpin	Unpin a session for the current user.
sessions update	Update session title, tags, or locale.
sessions budget-check check	Check all budgets for a session.
sessions budgets list	List all budgets for a session.
sessions databases create	Create a new SQL database inside a session.
sessions databases delete	Delete a session SQL database.
sessions databases get	Get metadata for a session SQL database.
sessions databases list	List all SQL databases created inside a session.
sessions databases schema get	Inspect the schema of a session SQL database.
sessions events list	List events for a session.
sessions events summary events	One-shot debug summary for a session: counts by type, first/last timestamps, turn count, error count.
sessions fs create	Create a file or directory in the session filesystem.
sessions fs delete	Delete a file or directory in the session filesystem.
sessions fs get	Get a file or directory at a path in the session filesystem.
sessions fs list	Get the root directory listing of session files.
sessions fs update	Update a file in the session filesystem.
sessions fs - copy	Copy a file in the session filesystem.
sessions fs - grep	Search files in the session filesystem.
sessions fs - move	Move or rename a file in the session filesystem.
sessions fs - search	Search files in the session filesystem, with surrounding context and paging.
sessions fs - stat	Get file metadata in the session filesystem.
sessions mcp-servers list	List the MCP servers added to one chat only.
sessions mcp-servers remove	Remove an MCP server added to one chat only.
sessions messages create	Create a user message in a session and start the next run.
sessions messages list	List materialized messages in a session, optionally limited to the most recent N.
sessions participants add	Add a member participant to a session.
sessions participants leave	Mark a session member participant as having left.
sessions participants list	List the participant history for a session.
sessions platform-chat ensure	Open the current user’s permanent platform conversation.
sessions resources list	List all resources registered in a session.
sessions sandbox get	Inspect a Session’s primary Sandbox and what it may touch.
sessions sandbox manage	Pause, resume, or delete the managed sandbox for a session.
sessions sse stream	Stream events via SSE.
sessions storage keys list	List all key-value pairs stored for a session.
sessions storage secrets batch	Encrypt and store multiple session secrets in one request.
sessions storage secrets delete	Delete a user-managed encrypted session secret by name.
sessions storage secrets list	List all secrets stored for a session without revealing values.
sessions tasks cancel	Request cooperative cancellation of a session task.
sessions tasks get	Get one session task with its recent message thread.
sessions tasks list	List background tasks owned by a session.
sessions tasks messages post	Send an inbound message to a session task.
sessions tasks push-configs create	Create a per-task push-notification config.
sessions tasks push-configs delete	Delete a per-task push-notification config.
sessions tasks push-configs list	List per-task push-notification configs.
sessions tool-results submit	Submit client-side tool results back to a waiting session.

sessions create

Create a new session.

everruns sessions create [OPTIONS]

Flag	Description
-H, --harness <HARNESS>	Harness ID or name (e.g. harness_xxx or “generic”). Omit to derive from the agent (when given), else the org default.
-a, --agent <AGENT>	Agent ID or name (optional, e.g. agent_xxx or “support”). When set without —harness, the session runs on the agent’s harness.
--title <TITLE>	Session title.
--locale <LOCALE>	Session locale (BCP 47, e.g. uk-UA)
--model <MODEL>	Model ID override (e.g. mod_xxx)
--virtual-user <VIRTUAL_USER>	Resident virtual user ID for unattended/background execution.
--system-prompt <SYSTEM_PROMPT>	Session-level system prompt override.
-t, --tag <TAGS>	Session tag (repeatable) Repeatable.
--capability <REF[=JSON]>	Session capability (repeatable). Format: REF or REF=JSON_CONFIG. Repeatable.
--hint <KEY=JSON>	Session client hint (repeatable). Format: KEY=JSON_VALUE. Repeatable.
--hints-json <JSON>	Session client hints JSON object.
--network-allow <PATTERN>	Network allow pattern (repeatable) Repeatable.
--network-block <PATTERN>	Network block pattern (repeatable) Repeatable.
--max-iterations <MAX_ITERATIONS>	Maximum LLM iterations per turn.
--secret <KEY=VALUE>	Session-scoped secret (repeatable, format: KEY=VALUE) Repeatable.
--budget-limit <[CURRENCY:]LIMIT>	Budget limit (repeatable). Format: [CURRENCY:]LIMIT. Currency defaults to usd. Examples: —budget-limit 10 ($10 USD) —budget-limit usd:10 ($10 USD, explicit) —budget-limit tokens:2000000 (2M token limit) Multiple limits stack — most restrictive wins. Repeatable.
--budget-soft-limit <[CURRENCY:]LIMIT>	Budget soft limit — pauses before hard stop. Same format as —budget-limit. Must pair with a —budget-limit of the same currency. Repeatable.

sessions watch

Watch session events in real time.

everruns sessions watch <SESSION>

Flag	Description
<SESSION>	Required. Session ID (e.g. ses_xxx)

sessions export

Export session messages as JSONL or an ATIF trajectory.

everruns sessions export [OPTIONS] <SESSION>

Flag	Description
<SESSION>	Required. Session ID (e.g. session_xxx)
--out <OUT>	File to write (defaults to stdout). Not -o/--output: that is the global output-format flag, and sharing its id made clap fill this with the format’s default, so every export wrote a file named text.
--format <FORMAT>	Export format: jsonl (one message per line, default) or atif (a single ATIF trajectory JSON document) One of jsonl, atif.

sessions archive

Archive a session so it drops out of default lists.

everruns sessions archive [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Move a finished session out of the active list
everruns sessions archive session_01h9 --reason 'Release shipped'

sessions cancel

Cancel the currently executing turn in a session.

everruns sessions cancel [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Stop a session that is running away
everruns sessions cancel session_01h9

sessions delete

Delete a session.

everruns sessions delete [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Archive a session, keeping it restorable
everruns sessions delete session_01h9 --reason 'Duplicate of the release session'

sessions fork

Fork a session into a new, independent session that copies its conversation history and workspace files.

everruns sessions fork [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session to fork (prefixed public id).
--overrides <OVERRIDES>	Request to fork a session.

Example:

# Branch from a session to try a different direction
everruns sessions fork session_01h9 --reason 'Try the rollback path'

sessions get

Get session details including status, agent, harness, and model.

everruns sessions get [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Show one session's state and configuration
everruns sessions get session_01h9

sessions context

Get the latest estimated context token breakdown for a session, grouped by system prompt, tools, rules, skills, MCP, subagents, and conversation.

everruns sessions context [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.

Example:

# See what is filling a session's context window
everruns sessions context session_01h9

sessions facets

Counts per status, source, and agent plus masthead metrics for the sessions list, over the same filters as list_sessions.

everruns sessions facets [OPTIONS]

Flag	Description
--agent-id <AGENT_ID>
--archived-only	Return only archived sessions.
--created-after <CREATED_AFTER>	Inclusive lower bound on created_at (RFC 3339).
--created-before <CREATED_BEFORE>	Exclusive upper bound on created_at (RFC 3339).
--include-archived	Include archived sessions.
--mine	Restrict to sessions owned by the calling user.
--order <ORDER>	created_at (default) or last_activity.
--playground-user-id <PLAYGROUND_USER_ID>
--search <SEARCH>	Case-insensitive title substring match.
--side-chats-only	Exclude the permanent Chat from side-conversation pagination.
--source <SOURCE>	Comma-separated sources (chat, api, slack, ag_ui, fcp, schedule, webhook, a2a…
--status <STATUS>	Comma-separated derived activities (running, paused, failed, completed, idle).

Example:

# Break the session list down by status, agent and source
everruns sessions facets --search triage

sessions stats

Get session counts by status.

everruns sessions stats [OPTIONS]

Example:

# Check token and cost totals across sessions
everruns sessions stats

sessions list

List sessions. Filter by agent_id, source, status, owner (mine), and creation window; search by title; order by created_at or last_activity. Supports pagination (limit/offset).

everruns sessions list [OPTIONS]

Flag	Description
--agent-id <AGENT_ID>
--archived-only	Return only archived sessions.
--created-after <CREATED_AFTER>	Inclusive lower bound on created_at (RFC 3339).
--created-before <CREATED_BEFORE>	Exclusive upper bound on created_at (RFC 3339).
--include-archived	Include archived sessions.
--limit <LIMIT>	Maximum number of items returned in this page.
--mine	Restrict to sessions owned by the calling user.
--offset <OFFSET>	Zero-based offset into the result set.
--order <ORDER>	created_at (default) or last_activity.
--playground-user-id <PLAYGROUND_USER_ID>
--search <SEARCH>	Case-insensitive title substring match.
--side-chats-only	Exclude the permanent Chat from side-conversation pagination.
--source <SOURCE>	Comma-separated sources (chat, api, slack, ag_ui, fcp, schedule, webhook, a2a…
--status <STATUS>	Comma-separated derived activities (running, paused, failed, completed, idle).

Example:

# Find recent sessions when you do not know the id
everruns sessions list --limit 20

sessions pin

Pin a session for the current user.

everruns sessions pin [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Keep a session at the top of the list
everruns sessions pin session_01h9 --reason 'Active incident'

sessions resume

Resume all paused session budgets for a session.

everruns sessions resume [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Restart a session that paused when a budget ran out
everruns sessions resume session_01h9 --reason 'Budget topped up'

sessions unarchive

Restore an archived session to default lists.

everruns sessions unarchive [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Bring an archived session back to the active list
everruns sessions unarchive session_01h9 --reason 'Release reopened'

sessions unpin

Unpin a session for the current user.

everruns sessions unpin [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Stop keeping a session at the top of the list
everruns sessions unpin session_01h9 --reason 'Incident resolved'

sessions update

Update session title, tags, or locale.

everruns sessions update [OPTIONS] [SESSION]

Flag	Description
--session <SESSION_ID>	Session’s prefixed public identifier.
--goal <GOAL>	Updated session objective.
--locale <LOCALE>	Session locale (BCP 47, e.g.
--tags <TAGS>	Tags for organizing and filtering sessions. Repeatable.
--title <TITLE>	Human-readable title for the session.
--virtual-user-id <VIRTUAL_USER_ID>	Optional resident virtual user used for unattended/background execution.

Example:

# Retitle a session so it is findable later
everruns sessions update session_01h9 --title 'Release triage' --reason 'Clarify the session topic'

sessions budget-check check

Check all budgets for a session.

everruns sessions budget-check check [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# See if any budget would stop this session from running
everruns sessions budget-check check session_01h9

sessions budgets list

List all budgets for a session.

everruns sessions budgets list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# List every budget that constrains a session
everruns sessions budgets list session_01h9

sessions databases create

Create a new SQL database inside a session.

everruns sessions databases create [OPTIONS] --name <name> --session-id <session_id>

Flag	Description
--name <NAME>	Required. Human-readable name.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Give a session a scratch SQL database to work with
everruns sessions databases create --session-id session_01h9 --name analytics --reason 'Store intermediate results'

sessions databases delete

Delete a session SQL database.

everruns sessions databases delete [OPTIONS] --name <name> --session-id <session_id>

Flag	Description
--name <NAME>	Required. Human-readable name.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Drop a session database once its data is exported
everruns sessions databases delete --session-id session_01h9 --name analytics --reason 'No longer needed'

sessions databases get

Get metadata for a session SQL database.

everruns sessions databases get [OPTIONS] --name <name> --session-id <session_id>

Flag	Description
--name <NAME>	Required. Human-readable name.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Check a session database's size and metadata
everruns sessions databases get --session-id session_01h9 --name analytics

sessions databases list

List all SQL databases created inside a session.

everruns sessions databases list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# See which databases a session has created
everruns sessions databases list session_01h9

sessions databases schema get

Inspect the schema of a session SQL database.

everruns sessions databases schema get [OPTIONS] --name <name> --session-id <session_id>

Flag	Description
--name <NAME>	Required. Human-readable name.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Inspect a session database's tables before writing queries
everruns sessions databases schema get --session-id session_01h9 --name analytics

sessions events list

List events for a session.

everruns sessions events list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.
--after-sequence <AFTER_SEQUENCE>	Forward cursor: only return events with sequence > after_sequence. Mutually exclusive with `b…
--around <AROUND>
--before-sequence <BEFORE_SEQUENCE>	Backward cursor: only events with sequence < before_sequence.
--exclude <EXCLUDE>	Omit these event types. Repeatable.
--exec-id <EXEC_ID>	Filter by context.exec_id.
--from-ts <FROM_TS>	created_at >= from_ts (RFC 3339).
--limit <LIMIT>	Maximum number of items returned in this page.
--order-desc	When true, return newest first; default oldest first.
--q <Q>	Full-text search via Postgres tsvector (substring fallback in-memory).
--since-id <SINCE_ID>
--tags <TAGS>	Tag any-match against events.tags. Repeatable.
--to-ts <TO_TS>	created_at <= to_ts (RFC 3339).
--tool-name <TOOL_NAME>	Match data.tool_name (useful for tool.* events).
--trace-id <TRACE_ID>	Filter by context.trace_id.
--turn-id <TURN_ID>	Filter by context.turn_id.
--types <TYPES>	Only these event types, e.g. Repeatable.
--window <WINDOW>	Window size for around (events on each side).

Example:

# Find what failed in a session's tool calls
everruns sessions events list session_01h9 --types tool.failed

# Search a session's events for a phrase, newest first
everruns sessions events list session_01h9 --q timeout --order-desc true

sessions events summary events

One-shot debug summary for a session: counts by type, first/last timestamps, turn count, error count.

everruns sessions events summary events [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Get a quick picture of a session (event counts, turns, errors) before reading events
everruns sessions events summary events session_01h9

sessions fs create

Create a file or directory in the session filesystem.

everruns sessions fs create [OPTIONS] --path <path> --session-id <session_id>

Flag	Description
--content <CONTENT>	File content (text or base64-encoded).
--encoding <ENCODING>	Content encoding: “text” or “base64”.
--is-directory	Whether to create a directory instead of a file (ignores content/encoding).
--is-readonly	Whether file is read-only.
--path <PATH>	Required. Path in the session filesystem (relative to the filesystem root).
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Seed a session with a file the agent should read
everruns sessions fs create --session-id session_01h9 --path /brief.md --content '# Brief' --reason 'Give the agent context'

sessions fs delete

Delete a file or directory in the session filesystem.

everruns sessions fs delete [OPTIONS] --path <path> --session-id <session_id>

Flag	Description
--path <PATH>	Required. Path in the session filesystem (relative to the filesystem root).
--recursive	Delete a directory and everything under it.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Remove a scratch directory from a session's filesystem
everruns sessions fs delete --session-id session_01h9 --path /tmp --recursive true --reason 'Clean up scratch files'

sessions fs get

Get a file or directory at a path in the session filesystem.

everruns sessions fs get [OPTIONS] --path <path> --session-id <session_id>

Flag	Description
--path <PATH>	Required. Path in the session filesystem (relative to the filesystem root).
--recursive	List nested entries recursively when the path is a directory.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Read a file the agent wrote in a session
everruns sessions fs get --session-id session_01h9 --path /report.md

sessions fs list

Get the root directory listing of session files.

everruns sessions fs list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.
--recursive	List nested entries recursively, not just the top level.

Example:

# See what files a session contains
everruns sessions fs list session_01h9

sessions fs update

Update a file in the session filesystem.

everruns sessions fs update [OPTIONS] --path <path> --session-id <session_id>

Flag	Description
--content <CONTENT>	New file content.
--encoding <ENCODING>	Content encoding: “text” or “base64”.
--expected-content <EXPECTED_CONTENT>	Content the file must currently hold for the write to happen. When set, the update is a comp…
--expected-encoding <EXPECTED_ENCODING>	Encoding of expected_content.
--is-readonly	Whether file is read-only.
--path <PATH>	Required. Path in the session filesystem (relative to the filesystem root).
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Overwrite a file in a session's filesystem
everruns sessions fs update --session-id session_01h9 --path /brief.md --content '# Updated brief' --reason 'Correct the scope'

sessions fs - copy

Copy a file in the session filesystem.

everruns sessions fs - copy [OPTIONS] --dst-path <dst_path> --session-id <session_id> --src-path <src_path>

Flag	Description
--dst-path <DST_PATH>	Required. Destination path (relative to the workspace filesystem root).
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--src-path <SRC_PATH>	Required. Source path (relative to the workspace filesystem root).

Example:

# Duplicate a file in a session's filesystem before editing it
everruns sessions fs - copy --session-id session_01h9 --src-path /notes.md --dst-path /notes.bak.md --reason 'Keep a backup'

sessions fs - grep

Search files in the session filesystem.

everruns sessions fs - grep [OPTIONS] --pattern <pattern> --session-id <session_id>

Flag	Description
--path-pattern <PATH_PATTERN>	Optional path glob to filter files (**/*.rs, docs/*.md).
--pattern <PATTERN>	Required. Regex pattern to search for.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Find which files in a session mention a word
everruns sessions fs - grep --session-id session_01h9 --pattern TODO

sessions fs - move

Move or rename a file in the session filesystem.

everruns sessions fs - move [OPTIONS] --dst-path <dst_path> --session-id <session_id> --src-path <src_path>

Flag	Description
--dst-path <DST_PATH>	Required. Destination path (relative to the workspace filesystem root).
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--src-path <SRC_PATH>	Required. Source path (relative to the workspace filesystem root).

Example:

# Rename a file in a session's filesystem
everruns sessions fs - move --session-id session_01h9 --src-path /draft.md --dst-path /final.md --reason 'Publish the draft'

sessions fs - search

Search files in the session filesystem, with surrounding context and paging.

everruns sessions fs - search [OPTIONS] --pattern <pattern> --session-id <session_id>

Flag	Description
--after-context <AFTER_CONTEXT>	Lines of context to return after each match.
--before-context <BEFORE_CONTEXT>	Lines of context to return before each match.
--limit <LIMIT>	Maximum matches to return.
--max-bytes <MAX_BYTES>	Byte ceiling on the returned payload.
--offset <OFFSET>	Number of matches to skip, for paging through a large result set.
--path-pattern <PATH_PATTERN>	Glob limiting which paths are searched.
--pattern <PATTERN>	Required. Regular expression to match against file contents.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Search file contents with surrounding lines
everruns sessions fs - search --session-id session_01h9 --pattern 'TODO|FIXME' --path-pattern '**/*.rs' --after-context 2

sessions fs - stat

Get file metadata in the session filesystem.

everruns sessions fs - stat [OPTIONS] --path <path> --session-id <session_id>

Flag	Description
--path <PATH>	Required. Path to the file or directory (relative to the workspace filesystem root).
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Check a file's size and type without reading it
everruns sessions fs - stat --session-id session_01h9 --path /report.md

sessions mcp-servers list

List the MCP servers added to one chat only.

everruns sessions mcp-servers list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# See which MCP servers were added to one chat only
everruns sessions mcp-servers list session_01h9

sessions mcp-servers remove

Remove an MCP server added to one chat only. Its tools leave from the next turn.

everruns sessions mcp-servers remove [OPTIONS] --name <name> --session-id <session_id>

Flag	Description
--name <NAME>	Required. Server name.
--session-id <SESSION_ID>	Required. Session the server was added to.

Example:

# Drop a chat-only MCP server so its tools leave from the next turn
everruns sessions mcp-servers remove --session-id session_01h9 --name github --reason 'No longer needed in this chat'

sessions messages create

Create a user message in a session and start the next run. The message content is an array of content parts, e.g. —content ’[{“type”:“text”,“text”:“Tell me a short, family-friendly joke.”}]’.

everruns sessions messages create [OPTIONS] --message <message> --session-id <session_id>

Flag	Description
--addressed-participant-id <ADDRESSED_PARTICIPANT_ID>
--controls <CONTROLS>
--external-actor <EXTERNAL_ACTOR>
--message <MESSAGE>	Required. Input message for creating a user message Only user messages can be created via the API. Age…
--metadata <METADATA>	Free-form metadata attached to this resource.
--request-id <REQUEST_ID>	Caller-chosen request id, carried through to the run and logs for correlation.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--tags <TAGS>	Free-form tags attached to this resource. Repeatable.

Example:

# Send a user message to a session and start the next run
everruns sessions messages create --session-id session_01h9 --message '{"content":[{"type":"text","text":"Why is the build failing on main?"}]}' --reason 'Ask about the failing build'

sessions messages list

List materialized messages in a session, optionally limited to the most recent N.

everruns sessions messages list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.
--limit <LIMIT>	Maximum number of items returned in this page.

Example:

# Read the latest messages of a session
everruns sessions messages list session_01h9 --limit 20

sessions participants add

Add a member participant to a session.

everruns sessions participants add [OPTIONS] --kind <kind> --session <session_id>

Flag	Description
--agent-id <AGENT_ID>	Agent to add when kind is agent.
--kind <KIND>	Required. Kind of actor participating in a session. One of agent, user.
--role <ROLE>
--session <SESSION_ID>	Required. Session that receives the participant.

Example:

# Bring a user into a running session
everruns sessions participants add --session session_01h9 --kind user --reason 'Bring in the on-call reviewer'

sessions participants leave

Mark a session member participant as having left.

everruns sessions participants leave [OPTIONS] --participant-id <participant_id> --session <session_id>

Flag	Description
--participant-id <PARTICIPANT_ID>	Required. Participant row to mark as left.
--session <SESSION_ID>	Required. Session that owns the participant.

Example:

# Remove one participant from a session
everruns sessions participants leave --session session_01h9 --participant-id part_01h9 --reason 'Review finished'

sessions participants list

List the participant history for a session.

everruns sessions participants list [OPTIONS] --session <session_id>

Flag	Description
--session <SESSION_ID>	Required. Session whose participant history should be returned.

Example:

# See who is attached to a session
everruns sessions participants list --session session_01h9

sessions platform-chat ensure

Open the current user’s permanent platform conversation.

everruns sessions platform-chat ensure [OPTIONS]

Example:

# Open your permanent platform conversation, creating it on first use
everruns sessions platform-chat ensure --reason 'Open the platform chat'

sessions resources list

List all resources registered in a session.

everruns sessions resources list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# List the files and other resources registered in a session
everruns sessions resources list session_01h9

sessions sandbox get

Inspect a Session’s primary Sandbox and what it may touch.

everruns sessions sandbox get [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# See what a session's sandbox can reach
everruns sessions sandbox get session_01h9

sessions sandbox manage

Pause, resume, or delete the managed sandbox for a session.

everruns sessions sandbox manage [OPTIONS] --action <action> --session-id <session_id>

Flag	Description
--action <ACTION>	Required. Operator action to take against a session’s managed sandbox. One of pause, resume, delete.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Pause a session's sandbox to stop paying for idle compute
everruns sessions sandbox manage --session-id session_01h9 --action pause --reason 'Idle overnight'

sessions sse stream

Stream events via SSE. Not supported in bash mode.

everruns sessions sse stream [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Watch a session's events live as they happen
everruns sessions sse stream session_01h9

sessions storage keys list

List all key-value pairs stored for a session.

everruns sessions storage keys list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# Inspect the key-value pairs a session has stored
everruns sessions storage keys list session_01h9

sessions storage secrets batch

Encrypt and store multiple session secrets in one request.

everruns sessions storage secrets batch [OPTIONS] --secrets <secrets> --session-id <session_id>

Flag	Description
--secrets <SECRETS>	Required. Secret values keyed by name, e.g.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.

Example:

# Give a session several credentials in one call
everruns sessions storage secrets batch --session-id session_01h9 --secrets '{"SERVICE_TOKEN":"s3cr3t","DB_PASSWORD":"hunter2"}' --reason 'Provision credentials for the deploy run'

sessions storage secrets delete

Delete a user-managed encrypted session secret by name.

everruns sessions storage secrets delete [OPTIONS] --name <name> --session-id <session_id>

Flag	Description
--name <NAME>	Required. Exact secret name to delete.
--session-id <SESSION_ID>	Required. Session that owns the secret.

Example:

# Revoke a credential from a session
everruns sessions storage secrets delete --session-id session_01h9 --name SERVICE_TOKEN --reason 'Token rotated'

sessions storage secrets list

List all secrets stored for a session without revealing values.

everruns sessions storage secrets list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.

Example:

# See which secrets a session has, without their values
everruns sessions storage secrets list session_01h9

sessions tasks cancel

Request cooperative cancellation of a session task.

everruns sessions tasks cancel [OPTIONS] --session-id <session_id> --task-id <task_id>

Flag	Description
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--task-id <TASK_ID>	Required. Task’s prefixed public identifier.

Example:

# Ask a runaway background task to stop
everruns sessions tasks cancel --session-id session_01h9 --task-id task_01h9 --reason 'Stuck on a dead host'

sessions tasks get

Get one session task with its recent message thread.

everruns sessions tasks get [OPTIONS] --session-id <session_id> --task-id <task_id>

Flag	Description
--after-id <AFTER_ID>	Return only messages newer than this message ID (exclusive cursor). When omitted, the most re…
--limit <LIMIT>	Maximum number of messages to return.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--task-id <TASK_ID>	Required. Task’s prefixed public identifier.

Example:

# Read a task's state and its recent messages
everruns sessions tasks get --session-id session_01h9 --task-id task_01h9

sessions tasks list

List background tasks owned by a session.

everruns sessions tasks list [OPTIONS] [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.
--kind <KIND>	Optional kind filter (subagent, external_agent, background_tool, …).
--state <STATE>	Optional state filter (queued, running, awaiting_input, succeeded, failed, canceled).

Example:

# See what background tasks a session is running
everruns sessions tasks list session_01h9 --state running

sessions tasks messages post

Send an inbound message to a session task.

everruns sessions tasks messages post [OPTIONS] --session-id <session_id> --task-id <task_id>

Flag	Description
--content <CONTENT>	Structured message parts (alternative to text).
--in-reply-to <IN_REPLY_TO>	Input request ID this message answers, when applicable.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--task-id <TASK_ID>	Required. Task’s prefixed public identifier.
--text <TEXT>	Plain-text message (alternative to content).

Example:

# Answer a task that is waiting for input
everruns sessions tasks messages post --session-id session_01h9 --task-id task_01h9 --text 'Use the staging database' --reason 'Unblock the migration task'

sessions tasks push-configs create

Create a per-task push-notification config.

everruns sessions tasks push-configs create [OPTIONS] --session-id <session_id> --task-id <task_id> --url <url>

Flag	Description
--event-filter <EVENT_FILTER>	Events that trigger delivery. Repeatable.
--secret <SECRET>	Optional HMAC-SHA256 signing secret.
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--task-id <TASK_ID>	Required. Task’s prefixed public identifier.
--url <URL>	Required. URL to POST task events to.

Example:

# Get a webhook call when a task finishes
everruns sessions tasks push-configs create --session-id session_01h9 --task-id task_01h9 --url https://example.com/hooks/tasks --secret "$WEBHOOK_SECRET" --reason 'Notify the deploy pipeline'

sessions tasks push-configs delete

Delete a per-task push-notification config.

everruns sessions tasks push-configs delete [OPTIONS] --config-id <config_id> --session-id <session_id> --task-id <task_id>

Flag	Description
--config-id <CONFIG_ID>	Required. Push config public id (tpc_…).
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--task-id <TASK_ID>	Required. Task’s prefixed public identifier.

Example:

# Stop webhook deliveries for a task
everruns sessions tasks push-configs delete --session-id session_01h9 --task-id task_01h9 --config-id cfg_01h9 --reason 'Pipeline retired'

sessions tasks push-configs list

List per-task push-notification configs.

everruns sessions tasks push-configs list [OPTIONS] --session-id <session_id> --task-id <task_id>

Flag	Description
--session-id <SESSION_ID>	Required. Session’s prefixed public identifier.
--task-id <TASK_ID>	Required. Task’s prefixed public identifier.

Example:

# Check where a task's webhooks are delivered
everruns sessions tasks push-configs list --session-id session_01h9 --task-id task_01h9

sessions tool-results submit

Submit client-side tool results back to a waiting session.

everruns sessions tool-results submit [OPTIONS] --tool-results <tool_results> [SESSION_ID]

Flag	Description
--session-id <SESSION_ID>	Session’s prefixed public identifier.
--tool-results <TOOL_RESULTS>	Required. Results for the pending client-side tool calls, one entry per tool_call_id.

Example:

# Return the result of a client-side tool call to a waiting session
everruns sessions tool-results submit session_01h9 --tool-results '[{"tool_call_id":"toolu_01","result":{"url":"https://example.com/orders/42"}}]' --reason 'Deliver the tool output'