openagent-dev Command Reference
Command list based on CLI 0.11.0. Install openagent-dev through the current Developer Skill.
This page follows the command tree implemented by the current parser. Command output is JSON. All download URLs and SHA-256 digests must come from the trusted Skill returned by the current official website's Build with local Agent action; they must not be hard-coded in this offline manual.
Installation and local checks
| Command | Purpose | Changes state? |
|---|---|---|
openagent-dev --version | Shows the version of the CLI that is actually executed. The renamed command is available from 0.11.7. | No |
openagent-dev doctor | Checks Python, SSH, ssh-keygen, local loopback ports, and known public keys. | No |
install --expected-sha256 SHA | Installs a script already verified against the Skill into the current user's directory. | Writes only to the local installation directory |
# Windows (for the verified temporary script)
py openagent-dev.py install --expected-sha256 <Skill-bound 64-character SHA-256>
# macOS / Linux
python3 openagent-dev.py install --expected-sha256 <Skill-bound 64-character SHA-256>
The installation result returns installed_path, command, and path_hint. First use the complete returned command to run --version again. If PATH still resolves to an older copy, do not reinstall repeatedly or modify shell configuration on your own.
Authentication and SSH keys
openagent-dev auth status
openagent-dev auth login
openagent-dev auth logout
openagent-dev ssh-key ensure
openagent-dev ssh-key ensure --create
openagent-dev ssh-key ensure --create --path <new_private_key_path>
auth statusonly checks the secure credential store. Useauth loginto explicitly retry OAuth; other commands that require authentication also open the browser when needed.auth logoutreports local deletion and server-side revocation separately.server_status=unconfirmedmust not be treated as confirmed revocation.ssh-key ensurewithout--createonly finds or validates a public key. Creating a new key requires explicit authorization, and the CLI refuses to overwrite an existing target.- The private key always remains on the local machine; the platform receives only the public key. The CLI uses the system Credential Manager, Keychain, or Secret Service and never falls back to a plaintext session file.
Select a source, create a Workspace, and connect
1. Query available sources without changing state
openagent-dev workspace sources --version-id <agent_version_id>
The result may include the current existing_workspace, recoverable published versions, and a recommended_source_version_id. A recommendation is not automatic authorization. The developer must explicitly choose among reusing the existing Workspace, selecting a historical snapshot, or starting from a fresh base environment.
2. Create or reuse
# Start from a published version snapshot confirmed by the developer
openagent-dev workspace create --version-id <target_draft_version_id> --source-version-id <source_version_id>
# Explicitly start from the platform base environment
openagent-dev workspace create --version-id <target_draft_version_id> --fresh
# Query the lifecycle of a known Workspace without changing state
openagent-dev workspace status --workspace-id <workspace_id>
A source Version restores only a compatible code and file snapshot. It does not copy the Agent card, Pricing, model, resource specifications, or WebUI ports. If sources already returns a reusable Workspace, use its ID instead of calling create to overwrite it.
3. Bind the public key and verify SSH for real
openagent-dev workspace connect --workspace-id <workspace_id>
status=active only means that the lifecycle is ready; it does not prove that SSH works. workspace connect verifies the local public/private key pair, binds an unbound Workspace using a stable idempotent intent, uses Workspace-isolated known_hosts, and performs a real -vvv authentication probe. Only after the result returns ssh_binding_status=bound and ssh_verified=true should you execute the complete returned ssh_command/scp_command exactly as provided.
4. Renew only the short-lived connection
openagent-dev workspace resume --workspace-id <workspace_id>
Run this only when the developer explicitly asks to continue using the same active + expired Workspace. resume does not create a new Sandbox, bind an SSH key, or replace the authentication probe performed by a subsequent workspace connect.
Wait parameters
| Parameter | Range | Default |
|---|---|---|
--timeout-seconds | 30..3600 | 600 |
--poll-interval-seconds | 1..30 | 3 |
--login-timeout-seconds | 60..600 | 300 |
WebUI application ports
CLI 0.11.0 or later supports only this query:
# Read confirmed ports and current connections
openagent-dev version webui-ports get --version-id <agent_version_id>
- Ports come from the confirmed configuration and platform configuration. The CLI cannot replace, clear, or refresh them, and does not permit arbitrary port edits.
- The result includes
sandbox_id,failure_code,ports,revision,sync_status,proxy_status, andwebui_urls. The portrevisionis not the website draft ETag. - Missing or expired connections are restored through the platform's readback flow for the same confirmed configuration. Do not rerun configuration or recreate the Sandbox to renew a connection.
pendingallows a later query.sync_status=failedrequires reportingfailure_code; a retired write intent is a failure, not an indefinitely pending or ready result.- Deliver URLs only when both status fields are ready. The CLI validates
/sandbox-proxy/{sandbox_id}/{port}/; use the complete returned URL and still test the real HTTP page and any WebSocket behavior.
Official website developer operations
# List the official website operations supported by this deployment and their write properties, offline
openagent-dev portal commands
In 0.11.0, portal commands use the same public APIs as the official website. Read-only commands can query directly. A write command must be the current action the developer explicitly requested and must include the command's required --confirm, stable --idempotency-key, original quoted --if-match, or temporary --body-file. Use the local portal commands output and --help as the authority for specific operations and parameters; do not guess from an old manual.
Compatibility skill link
openagent-dev skill-link create --version-id <VERSION_ID>
This compatibility entry point is still accepted by the parser. The recommended primary flow remains clicking Build with local Agent on the official website and copying the complete trusted prompt bound to the current Agent and Version.
Operations that still do not exist or cannot be substituted
| Command or assumption | Current behavior | Correct path |
|---|---|---|
openagent-dev sync | There is no general-purpose synchronization command. | After authorization, follow Safe synchronization using the exact SSH/SCP parameters returned by connect. |
openagent-dev workspace close/delete/publish | These Workspace subcommands do not exist. | Do not construct internal API calls. Publish through the website or a listed, controlled portal operation. |
| Execute an old SSH string from status directly | It does not prove key binding, host-key verification, or successful authentication. | Run workspace connect first. |
| Call raw platform HTTP endpoints directly | This bypasses the CLI's authentication, idempotency, digest verification, and redaction boundaries. | Use a public CLI command or the official website. |
Common stable errors
| Error | Response |
|---|---|
CLI_DIGEST_MISMATCH | Stop. Obtain the bound download information again from the current Skill; do not change the expected digest. |
WORKSPACE_TIMEOUT | Keep the returned Workspace ID and continue querying it with status; do not call create again. |
SSH_AGENT_KEY_NOT_LOADED / SSH_PRIVATE_KEY_PASSPHRASE_REQUIRED | Unlock or load the original private key in the same user session, then rerun connect for the same Workspace; do not switch keys. |
SSH_HOST_KEY_CHANGED | Stop immediately. Do not retry the network request or overwrite known_hosts. |
SSH_CONNECTION_FAILED | Use the returned timeout/refused/dns/unreachable/closed reason to distinguish a network failure from a platform entry-point failure. |
DEVELOPER_WORKSPACE_WEBUI_WRITE_RETIRED | Preserve failure_code; the old write has failed, so do not report ready or wait indefinitely. |
PORTAL_RESULT_UNKNOWN | The result of the write is unknown. Query or recover the same business intent; do not resubmit it with a different idempotency key. |