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 <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent resume
resume an Agent
Text
socra agent resume <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent provision
provision an Agent
Text
socra agent provision <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent wake
wake an Agent
Text
socra agent wake <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent upgrade
upgrade an Agent
Text
socra agent upgrade <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent capacity
Show seat capacity
Text
socra agent capacity [options]
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent usage
Show Agent usage
Text
socra agent usage <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent create
Create an Agent
Text
socra agent create <USERNAME> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
USERNAME | username | Yes |
Scroll to see all columns.
| 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 <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| 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]
Scroll to see all columns.
| 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 <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent delete
Delete an Agent and managed resources
Text
socra agent delete <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent activity
Get an activity snapshot without waking
Text
socra agent activity <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--after VALUE | Event cursor |
--json | Print JSON output |
socra agent listen
Watch progress without waking
Text
socra agent listen <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| 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]
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent model list
List cached models; --refresh wakes the computer
Text
socra agent model list <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| 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 <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection get
Read connection status
Text
socra agent connection get <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection check
Wake and check connection
Text
socra agent connection check <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection connect
Display sign-in code and wait for ChatGPT connection
Text
socra agent connection connect <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| 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 <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection cancel
Cancel pending ChatGPT sign-in
Text
socra agent connection cancel <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent secret create
Create a secret
Text
socra agent secret create <AGENT> <NAME> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
NAME | Environment variable name | Yes |
Scroll to see all columns.
| 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 <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent secret get
Get secret metadata (never its value)
Text
socra agent secret get <AGENT> <NAME> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
NAME | Environment variable name | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent secret update
Rotate a secret
Text
socra agent secret update <AGENT> <NAME> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
NAME | Environment variable name | Yes |
Scroll to see all columns.
| 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 <AGENT> <NAME> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
NAME | Environment variable name | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent message list
List mailbox messages
Text
socra agent message list <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| 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]
Scroll to see all columns.
| 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 <MESSAGE> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
MESSAGE | message | Yes |
Scroll to see all columns.
| 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 <MESSAGE> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
MESSAGE | message | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent message retry
Retry a mailbox invocation
Text
socra agent message retry <MESSAGE> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
MESSAGE | message | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent messages
List mailbox messages
Text
socra agent messages <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| 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 <REPOSITORY> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
REPOSITORY | GitHub owner/repository | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent repository list
List repositories
Text
socra agent repository list [AGENT] [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Optional Agent username or ID | No |
Scroll to see all columns.
| 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 <REPOSITORY> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
REPOSITORY | Repository ID | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent repository add
Register repository and grant write access
Text
socra agent repository add <AGENT> <REPOSITORY> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
REPOSITORY | GitHub owner/repository | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | JSON output |
socra agent repository revoke
Revoke a grant
Text
socra agent repository revoke <GRANT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
GRANT | grant | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent repository grant create
Grant repository access
Text
socra agent repository grant create <AGENT> <REPOSITORY> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Agent username or id | Yes |
REPOSITORY | Repository ID | Yes |
Scroll to see all columns.
| 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]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
AGENT | Optional Agent username or ID | No |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent repository grant delete
Revoke a grant
Text
socra agent repository grant delete <GRANT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
GRANT | grant | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent github start
Get GitHub installation URL
Text
socra agent github start [options]
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent github status
Get GitHub connection
Text
socra agent github status [options]
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent github disconnect
Disconnect GitHub
Text
socra agent github disconnect [options]
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent github connect
Open GitHub and wait for installation
Text
socra agent github connect [options]
Scroll to see all columns.
| Option | Description |
|---|---|
--json | JSON output |
See Troubleshooting for related guidance.