Interfaces

Runtime CLI reference

Run commands, continue sessions, and read or mutate files with the runtime client.

On this page+

Before you run
Command sessions
exec_command
write_command_stdin
read_command_lines
Files and attribution
file_read
file_write
file_edit
file_blame
Scope, request IDs, and exits

Before you run

Every runtime operation requires the global --sandbox-id ID selector before the operation is sent. Discover an ID with sandbox-manager-cli list_sandboxes, then place the selector anywhere clap accepts a global option.

Shell

sandbox-runtime-cli --sandbox-id ID help
sandbox-runtime-cli --sandbox-id ID help exec_command

Command text and stdin are trailing positional values. Quote shell metacharacters that must reach the sandbox unchanged. See Files and commands for end-to-end session workflows.

Find an operation

Showing 7 of 7 commands.

Command sessions

Start a command, write input, and page its stable transcript.

`exec_command`

Start a sandbox shell command

Session state

Start a shell command in a workspace session. Omit workspace_session_id to use an automatic publish_then_destroy session.

When to use it

Use workspace_session_id only when an existing managed session is available.
If status is running, retain command_session_id for read_command_lines or write_command_stdin.
A terminal automatic command captures and publishes filesystem changes before destroying its session.

Syntax

Usage

sandbox-runtime-cli --sandbox-id ID exec_command [--workspace-session-id ID] [--timeout-ms N] [--yield-time-ms N] COMMAND

Arguments

Argument	Type	Required	Description
`--sandbox-id ID (global)`	`string`	Yes	Target sandbox id (selects the daemon to query).
`--workspace-session-id ID`	`string`	No	Existing workspace session id to run inside. Omit to create a session with finalize policy publish_then_destroy.
`COMMAND`	`string`	Yes	Shell command text.
`--timeout-ms N`	`integer`	No	Command timeout in milliseconds.
`--yield-time-ms N`	`integer`	No	Initial output wait in milliseconds.

Examples

Shell

sandbox-runtime-cli --sandbox-id ID exec_command pwd
sandbox-runtime-cli --sandbox-id ID exec_command --workspace-session-id ws-1 --yield-time-ms 0 "sleep 30"

Representative result

JSON output

{
  "command_session_id": "namespace_execution_42",
  "workspace_session_id": "workspace_17",
  "status": "running",
  "exit_code": null,
  "wall_time_seconds": 0.25,
  "command_total_time_seconds": 0.25,
  "start_offset": 0,
  "end_offset": 2,
  "total_lines": 2,
  "original_token_count": 4,
  "output": "building…\n"
}

Result contract: status is running, ok, error, timed_out, or cancelled. A terminal result can include publication fields.

Related operationswrite_command_stdin read_command_lines

`write_command_stdin`

Write to a running command

Session state

Append text to the stdin stream of a running command session and return a bounded output yield.

When to use it

Use a command_session_id returned while exec_command is still running.
stdin is written exactly as supplied; include a newline for line-oriented programs.
The result uses the command-output shape and may become terminal after the write.

Syntax

Usage

sandbox-runtime-cli --sandbox-id ID write_command_stdin --command-session-id ID [--yield-time-ms N] TEXT

Arguments

Argument	Type	Required	Description
`--sandbox-id ID (global)`	`string`	Yes	Target sandbox id (selects the daemon to query).
`--command-session-id ID`	`string`	Yes	Command session id returned by exec_command.
`TEXT`	`string`	Yes	Text to write to stdin.
`--yield-time-ms N`	`integer`	No	Output wait after writing stdin.

Examples

Shell

sandbox-runtime-cli --sandbox-id ID write_command_stdin --command-session-id cmd-1 hello

Representative result

JSON output

{
  "command_session_id": "namespace_execution_42",
  "workspace_session_id": "workspace_17",
  "status": "ok",
  "exit_code": 0,
  "wall_time_seconds": 0.25,
  "command_total_time_seconds": 0.25,
  "start_offset": 0,
  "end_offset": 4,
  "total_lines": 4,
  "original_token_count": 4,
  "output": "accepted\ndone\n"
}

Result contract: The response contains only a bounded transcript window.

Related operationsexec_command read_command_lines

`read_command_lines`

Page a command transcript

Read-only

Read rendered command output for a command session using stable line offsets.

When to use it

Start at offset 0, then continue from end_offset until it reaches total_lines.
The command may still be running; status and offsets are a point-in-time snapshot.
Reading output does not extend or trigger workspace-session lifecycle behavior.

Syntax

Usage

sandbox-runtime-cli --sandbox-id ID read_command_lines --command-session-id ID [--start-offset N] [--limit N]

Arguments

Argument	Type	Required	Description
`--sandbox-id ID (global)`	`string`	Yes	Target sandbox id (selects the daemon to query).
`--command-session-id ID`	`string`	Yes	Command session id returned by exec_command.
`--start-offset N`	`integer`	No; default 0	First transcript line offset. Defaults to 0.
`--limit N`	`integer`	No; default 200	Maximum transcript rows to return. Defaults to 200; maximum 1000.

Examples

Shell

sandbox-runtime-cli --sandbox-id ID read_command_lines --command-session-id cmd-1 --start-offset 0 --limit 100

Representative result

JSON output

{
  "command_session_id": "namespace_execution_42",
  "workspace_session_id": "workspace_17",
  "status": "ok",
  "exit_code": 0,
  "wall_time_seconds": 0.25,
  "command_total_time_seconds": 0.25,
  "start_offset": 2,
  "end_offset": 4,
  "total_lines": 4,
  "original_token_count": 4,
  "output": "accepted\ndone\n"
}

Result contract: original_token_count describes the untruncated source before rendering bounds.

Related operationsexec_command write_command_stdin

Files and attribution

Read snapshots, publish file mutations, and inspect line ownership.

`file_read`

Read a UTF-8 text window

Read-only

Read a UTF-8 window from a repository-relative or workspace-root-absolute path in the published snapshot or a live session.

When to use it

Omit workspace_session_id for the published snapshot; include it for uncommitted session content.
Follow next_offset while truncated is true to page long files.
Only UTF-8 regular files are supported.

Syntax

Usage

sandbox-runtime-cli --sandbox-id ID file_read --path FILE [--offset N] [--limit N] [--workspace-session-id ID]

Arguments

Argument	Type	Required	Description
`--sandbox-id ID (global)`	`string`	Yes	Target sandbox id (selects the daemon to query).
`--path FILE`	`string`	Yes	Repository-relative or workspace-root-absolute path to read.
`--offset N`	`integer`	No; default 1	1-indexed line number to start reading from. Defaults to 1.
`--limit N`	`integer`	No; default 2000	Maximum number of lines to read. Defaults to 2000; must be 1..=2000.
`--workspace-session-id ID`	`string`	No	Existing workspace session id to read inside. Omit to read the snapshot.

Examples

Shell

sandbox-runtime-cli --sandbox-id ID file_read --path README.md
sandbox-runtime-cli --sandbox-id ID file_read --path src/main.rs --offset 20 --limit 40

Representative result

JSON output

{
  "path": "README.md",
  "content": "# Example\n\nProject overview…\n",
  "start_line": 1,
  "num_lines": 3,
  "total_lines": 3,
  "bytes_read": 31,
  "total_bytes": 31,
  "next_offset": null,
  "truncated": false
}

Result contract: next_offset is non-null when another window is available.

Related operationsfile_write file_edit file_blame

`file_write`

Create or overwrite a file

Changes state

Write content to a path in a live session, or publish a new attributed layer when no session is supplied.

When to use it

Use only when overwriting the complete target file is intended.
A session-scoped write stays private until that session resolves.
Without a session, the runtime publishes a layer owned by operation:<request_id>.

Syntax

Usage

sandbox-runtime-cli --sandbox-id ID file_write --path FILE --content TEXT [--workspace-session-id ID]

Arguments

Argument	Type	Required	Description
`--sandbox-id ID (global)`	`string`	Yes	Target sandbox id (selects the daemon to query).
`--path FILE`	`string`	Yes	Repository-relative or workspace-root-absolute path to write.
`--content TEXT`	`string`	Yes	File content to write.
`--workspace-session-id ID`	`string`	No	Existing workspace session id to write inside. Omit to publish a layer.

Examples

Shell

sandbox-runtime-cli --sandbox-id ID file_write --path notes.txt --content 'hello'
sandbox-runtime-cli --sandbox-id ID file_write --path notes.txt --content 'hello' --workspace-session-id ws-1

Representative result

JSON output

{
  "type": "update",
  "path": "notes.txt",
  "bytes_written": 12
}

Result contract: type is create for a new path or update for an existing regular file.

Related operationsfile_read file_edit file_blame

`file_edit`

Apply ordered exact replacements

Changes state

Apply ordered exact-string replacements in a live session, or publish one attributed layer when no session is supplied.

When to use it

Each item requires old_string and new_string; replace_all defaults to false.
Without replace_all, old_string must occur exactly once. Empty, missing, ambiguous, and no-op edits fail.
Edits run in array order; omitting a session publishes a durable layer immediately.

Syntax

Usage

sandbox-runtime-cli --sandbox-id ID file_edit --path FILE --edits JSON [--workspace-session-id ID]

Arguments

Argument	Type	Required	Description
`--sandbox-id ID (global)`	`string`	Yes	Target sandbox id (selects the daemon to query).
`--path FILE`	`string`	Yes	Repository-relative or workspace-root-absolute path to edit.
`--edits JSON`	`array`	Yes	JSON array of { old_string, new_string, replace_all? } edits, applied in order.
`--workspace-session-id ID`	`string`	No	Existing workspace session id to edit inside. Omit to publish a layer.

Examples

Shell

sandbox-runtime-cli --sandbox-id ID file_edit --path notes.txt --edits '[{"old_string":"a","new_string":"b"}]'
sandbox-runtime-cli --sandbox-id ID file_edit --path notes.txt --edits '[{"old_string":"a","new_string":"b","replace_all":true}]' --workspace-session-id ws-1

Representative result

JSON output

{
  "type": "edit",
  "path": "notes.txt",
  "edits_applied": 1,
  "replacements": 2,
  "bytes_written": 26
}

Result contract: edits_applied counts edit objects; replacements counts occurrences changed.

Related operationsfile_read file_write file_blame

`file_blame`

Inspect per-line published ownership

Read-only

Return each line owner for a published path from the latest auditability event.

When to use it

Use this after commands, writes, or edits have created auditability events.
Ranges are 1-indexed and tile the latest known file content.
Treat owner strings as opaque. A missing auditability record returns not_found.

Syntax

Usage

sandbox-runtime-cli --sandbox-id ID file_blame --path FILE

Arguments

Argument	Type	Required	Description
`--sandbox-id ID (global)`	`string`	Yes	Target sandbox id (selects the daemon to query).
`--path FILE`	`string`	Yes	Repository-relative path to blame.

Examples

Shell

sandbox-runtime-cli --sandbox-id ID file_blame --path README.md

Representative result

JSON output

{
  "path": "notes.txt",
  "ranges": [
    {
      "start_line": 1,
      "line_count": 4,
      "owner": "original"
    },
    {
      "start_line": 5,
      "line_count": 2,
      "owner": "operation:request-id"
    }
  ]
}

Result contract: owner can be workspace_session:<id>, operation:<id>, original, or unknown.

Related operationsfile_read file_write file_edit

Scope, request IDs, and exits

Add --request-id VALUE when another system needs a stable request identity. Published direct file mutations are attributed to operation:<request-id>. Without it, the client generates an ID.

Shell

sandbox-runtime-cli --sandbox-id ID --request-id change-42 file_write --path status.txt --content ready

Exit 0 writes success JSON to stdout, exit 1 writes a gateway or operation error to stderr, and exit 2 reports local syntax, validation, or configuration failure. A command’s own non-zero exit_code is data in the successful operation response; it is not the CLI process exit status.