CLI
Use socra agent to manage CoAgents 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
CoAgent-targeted commands accept a username or CoAgent 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 CoAgent CLI command declarations. Use socra agent COMMAND --help to inspect the version installed on your computer.
AGENT means your CoAgent's username or CoAgent 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 CoAgent'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 |
--runtime VALUE | codex or claude; agent must be sleeping or paused |
--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 |
--recovery-only | Read persisted recovery metadata without contacting the runtime |
--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 assign
Assign to a sleeping Agent with an updated runtime
Text
socra agent connection assign <CONNECTION> <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | connection | Yes |
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection unassign
Remove from a sleeping Agent
Text
socra agent connection unassign <CONNECTION> <AGENT> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | connection | Yes |
AGENT | Agent username or id | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection create
Create an AI connection
Text
socra agent connection create <NAME> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
NAME | name | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--provider VALUE | Provider (chatgpt or claude) |
--json | Print JSON output |
socra agent connection list
List your AI connections
Text
socra agent connection list [options]
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection token
Connect using a Claude subscription token from claude setup-token
Text
socra agent connection token <CONNECTION> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | connection | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--stdin | Read token from stdin |
--file VALUE | Read token from file |
--json | Print JSON output |
socra agent connection login
Start provider browser sign-in
Text
socra agent connection login <CONNECTION> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | connection | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection code
Submit Claude browser sign-in code
Text
socra agent connection code <CONNECTION> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | connection | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--attempt VALUE | Sign-in attempt from connection login |
--stdin | Read code from stdin |
--file VALUE | Read code from file |
--json | Print JSON output |
socra agent connection verify
Verify and refresh credentials
Text
socra agent connection verify <CONNECTION> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | connection | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection delete
Delete an AI connection
Text
socra agent connection delete <CONNECTION> [options]
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | connection | Yes |
Scroll to see all columns.
| Option | Description |
|---|---|
--json | Print JSON output |
socra agent connection get
Read connection status
Text
socra agent connection get <CONNECTION>
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | Connection ID or legacy Agent username | Yes |
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
Disconnect ChatGPT
Text
socra agent connection disconnect <CONNECTION>
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | Connection ID or legacy Agent username | Yes |
socra agent connection cancel
Cancel pending sign-in
Text
socra agent connection cancel <CONNECTION>
Scroll to see all columns.
| Argument | Description | Required |
|---|---|---|
CONNECTION | Connection ID or legacy Agent username | Yes |
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 sleep
Sleep the current Agent if its mailbox is empty
Text
socra agent message sleep [options]
Scroll to see all columns.
| Option | Description |
|---|---|
--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 discover
Refresh delegated repository candidate metadata without source grants
Text
socra agent repository discover [options]
Scroll to see all columns.
| Option | Description |
|---|---|
--provider VALUE | all (default) or github |
socra agent repository discovery delegate
Delegate metadata discovery (Account admin/owner)
Text
socra agent repository discovery delegate <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 repository discovery status
Read metadata delegation
Text
socra agent repository discovery status <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 repository discovery revoke
Revoke metadata discovery (Account admin/owner)
Text
socra agent repository discovery revoke <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 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
Assign repository access to an Agent
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 |
--permission VALUE | read or write (default write) |
--actions-permission VALUE | Explicit Actions read or write (default read; omitted updates preserve current grant) |
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) |
--actions-permission VALUE | Explicit Actions read or write (default read; omitted updates preserve current grant) |
--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 capabilities
Read approved installation permissions (admin only)
Text
socra agent github capabilities [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.