--- title: "CLI" canonical: https://workspace.socra.com/docs/agents/reference/cli --- # CLI Use `socra agent` to manage agents from a terminal. Sign in to the intended Account before running commands. ## Install and inspect ```sh socra install agent socra account status socra agent --help ``` Agent-targeted commands accept a username or Agent ID. The CLI resolves usernames within the active Account. Use each command's `--help` for its options. ## Read the reference The command reference below is generated from the published Agent CLI command declarations. Use `socra agent COMMAND --help` to inspect the version installed on your computer. `AGENT` means your agent's username or Agent ID. Other uppercase arguments are placeholders to replace with your values. Angle brackets mark required arguments; square brackets mark optional arguments. Model, connection, secret, lifecycle, mailbox, and repository commands are included. Runtime-only operations such as mailbox pull and acknowledgement require the agent's own identity. ## socra agent pause pause an Agent ```text socra agent pause [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent resume resume an Agent ```text socra agent resume [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent provision provision an Agent ```text socra agent provision [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent wake wake an Agent ```text socra agent wake [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent upgrade upgrade an Agent ```text socra agent upgrade [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent capacity Show seat capacity ```text socra agent capacity [options] ``` | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent usage Show Agent usage ```text socra agent usage [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent create Create an Agent ```text socra agent create [options] ``` | Argument | Description | Required | | --- | --- | --- | | `USERNAME` | username | Yes | | Option | Description | | --- | --- | | `--daily-input-tokens VALUE` | Daily input tokens, or unlimited | | `--daily-output-tokens VALUE` | Daily output tokens, or unlimited | | `--runtime VALUE` | codex or claude (default codex) | | `--json` | Print JSON output | ## socra agent update Update identity, model, effort, or budgets ```text socra agent update [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--daily-input-tokens VALUE` | Daily input tokens, or unlimited | | `--daily-output-tokens VALUE` | Daily output tokens, or unlimited | | `--username VALUE` | New username | | `--model VALUE` | Model identifier | | `--reasoning-effort VALUE` | Supported effort or default | | `--json` | Print JSON output | ## socra agent list List Agents ```text socra agent list [options] ``` | Option | Description | | --- | --- | | `--limit VALUE` | Page size (1–100) | | `--after VALUE` | Page cursor | | `--json` | Print JSON output | ## socra agent get Get an Agent ```text socra agent get [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent delete Delete an Agent and managed resources ```text socra agent delete [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent activity Get an activity snapshot without waking ```text socra agent activity [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--after VALUE` | Event cursor | | `--json` | Print JSON output | ## socra agent listen Watch progress without waking ```text socra agent listen [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--once` | One snapshot | | `--json` | JSON snapshots | ## socra agent runtime-settings Read own settings as the current Agent principal ```text socra agent runtime-settings [options] ``` | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent model list List cached models; --refresh wakes the computer ```text socra agent model list [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--refresh` | Refresh from Codex | | `--json` | Print JSON output | ## socra agent model refresh Wake computer and refresh available models ```text socra agent model refresh [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent connection get Read connection status ```text socra agent connection get [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent connection check Wake and check connection ```text socra agent connection check [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent connection connect Display sign-in code and wait for ChatGPT connection ```text socra agent connection connect [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--once` | Return device flow details without waiting | | `--json` | Print JSON output | ## socra agent connection disconnect Sign out of ChatGPT ```text socra agent connection disconnect [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent connection cancel Cancel pending ChatGPT sign-in ```text socra agent connection cancel [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent secret create Create a secret ```text socra agent secret create [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | `NAME` | Environment variable name | Yes | | Option | Description | | --- | --- | | `--stdin` | Read secret from standard input | | `--file VALUE` | Read secret from file | | `--env VALUE` | Read secret from local environment variable | | `--json` | Print JSON output | ## socra agent secret list List secret metadata ```text socra agent secret list [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent secret get Get secret metadata (never its value) ```text socra agent secret get [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | `NAME` | Environment variable name | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent secret update Rotate a secret ```text socra agent secret update [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | `NAME` | Environment variable name | Yes | | Option | Description | | --- | --- | | `--stdin` | Read secret from standard input | | `--file VALUE` | Read secret from file | | `--env VALUE` | Read secret from local environment variable | | `--json` | Print JSON output | ## socra agent secret delete Delete secret and stored versions ```text socra agent secret delete [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | `NAME` | Environment variable name | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent message list List mailbox messages ```text socra agent message list [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--limit VALUE` | Page size (1–100) | | `--after VALUE` | Page cursor | | `--status VALUE` | queued, delivered, or acknowledged | | `--json` | Print JSON output | ## socra agent message pull Pull work as the current Agent principal ```text socra agent message pull [options] ``` | Option | Description | | --- | --- | | `--in-flight VALUE` | Comma-separated message IDs already in flight | | `--json` | Print JSON output | ## socra agent message acknowledge Acknowledge work as the current Agent principal ```text socra agent message acknowledge [options] ``` | Argument | Description | Required | | --- | --- | --- | | `MESSAGE` | message | Yes | | Option | Description | | --- | --- | | `--outcome VALUE` | succeeded, failed, or canceled | | `--result VALUE` | Result summary | | `--error VALUE` | Failure summary | | `--json` | Print JSON output | ## socra agent message cancel Cancel a mailbox invocation ```text socra agent message cancel [options] ``` | Argument | Description | Required | | --- | --- | --- | | `MESSAGE` | message | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent message retry Retry a mailbox invocation ```text socra agent message retry [options] ``` | Argument | Description | Required | | --- | --- | --- | | `MESSAGE` | message | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent messages List mailbox messages ```text socra agent messages [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | Option | Description | | --- | --- | | `--limit VALUE` | Page size (1–100) | | `--after VALUE` | Page cursor | | `--status VALUE` | queued, delivered, or acknowledged | | `--json` | Print JSON output | ## socra agent repository create Register a repository ```text socra agent repository create [options] ``` | Argument | Description | Required | | --- | --- | --- | | `REPOSITORY` | GitHub owner/repository | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent repository list List repositories ```text socra agent repository list [AGENT] [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Optional Agent username or ID | No | | Option | Description | | --- | --- | | `--limit VALUE` | Page size (1–100) | | `--json` | Print JSON output | ## socra agent repository remove Remove repository and grants ```text socra agent repository remove [options] ``` | Argument | Description | Required | | --- | --- | --- | | `REPOSITORY` | Repository ID | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent repository add Register repository and grant write access ```text socra agent repository add [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | `REPOSITORY` | GitHub owner/repository | Yes | | Option | Description | | --- | --- | | `--json` | JSON output | ## socra agent repository revoke Revoke a grant ```text socra agent repository revoke [options] ``` | Argument | Description | Required | | --- | --- | --- | | `GRANT` | grant | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent repository grant create Grant repository access ```text socra agent repository grant create [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Agent username or id | Yes | | `REPOSITORY` | Repository ID | Yes | | Option | Description | | --- | --- | | `--permission VALUE` | read or write (default write) | | `--json` | Print JSON output | ## socra agent repository grant list List grants ```text socra agent repository grant list [AGENT] [options] ``` | Argument | Description | Required | | --- | --- | --- | | `AGENT` | Optional Agent username or ID | No | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent repository grant delete Revoke a grant ```text socra agent repository grant delete [options] ``` | Argument | Description | Required | | --- | --- | --- | | `GRANT` | grant | Yes | | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent github start Get GitHub installation URL ```text socra agent github start [options] ``` | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent github status Get GitHub connection ```text socra agent github status [options] ``` | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent github disconnect Disconnect GitHub ```text socra agent github disconnect [options] ``` | Option | Description | | --- | --- | | `--json` | Print JSON output | ## socra agent github connect Open GitHub and wait for installation ```text socra agent github connect [options] ``` | Option | Description | | --- | --- | | `--json` | JSON output | See [Troubleshooting](/docs/agents/troubleshooting) for related guidance.