OpenDeploy CLI

Official OpenDeploy CLI for agent-first deployments.

The CLI is the versioned execution surface for OpenDeploy. Agent skills should call this package instead of embedding gateway API calls in Markdown.

Install

Install globally:

npm install -g @opendeploydev/cli
opendeploy --help

The user-facing package is always @opendeploydev/cli. Native packages such as @opendeploydev/cli-darwin-arm64 are optional dependencies that npm installs automatically for the current platform; they are not the normal install path. The published npm package does not include the readable CLI source file; it ships a small launcher and the selected native binary package. Platform packages intentionally do not expose bin entries; the main package owns the opendeploy command.

Local Development

npm install
npm run build
npm test
npx . --help

npm run build bundles bin/opendeploy.js, creates a native OpenDeploy binary for the current platform, and writes the npm launcher to dist/opendeploy.js. The package bin entries point at dist/opendeploy.js, so run the build before npx ., npm pack, or npm publish. The build source file is intentionally excluded from the published npm tarball.

To build platform packages for release:

npm run build:platforms
npm run pack:platforms

Release order:

npm run build:platforms
npm run publish:platforms -- --provenance
npm publish --provenance

Publish platform packages first so the main package optional dependencies are available when users install @opendeploydev/cli.

If npm asks for 2FA, pass the same one-time password to both publishes:

npm run publish:platforms -- --otp=123456
npm publish --otp=123456

Agent-Safe Quickstart

Read-only checks:

opendeploy preflight . --json
opendeploy doctor --json
opendeploy update check --json
opendeploy status --json
opendeploy auth status --json
opendeploy env scan . --json
opendeploy config features --json

preflight and update check include both npm CLI version status and the OpenDeploy skill-plugin manifest status, so agents do not need separate plugin-root jq or raw curl probes.

Create a guest deploy credential only after explicit user approval:

opendeploy auth guest --json

Generate a read-only deploy plan:

opendeploy deploy plan . --json

For complex first deploys, agents should execute the plan step by step and adjust from each structured result:

opendeploy context resolve --json
opendeploy deploy step --plan .opendeploy/plan.json --step dependencies --json
opendeploy deploy verify --plan .opendeploy/plan.json --after dependencies --json
opendeploy deploy step --plan .opendeploy/plan.json --step source --project <project-id> --project-name <name> --region-id <region-id> --json
opendeploy dependencies wait <project-id> --json
opendeploy dependencies update-connection <project-id> <dependency-id> --body db-credentials.json --json
opendeploy dependencies port-access enable <project-id> <dependency-id> --confirm-security-sensitive --json
opendeploy dependencies port-access disable <project-id> <dependency-id> --json
opendeploy services env reconcile <project-id> <service-id> --from-plan .opendeploy/plan.json --json
opendeploy services config patch <service-id> --port <port> --json
opendeploy services create <project-id> --body service.json --json
opendeploy deploy wait <deployment-id> --follow --json
opendeploy deploy progress <deployment-id> --json
opendeploy logs diagnose <deployment-id> --json

deploy wait --follow --json emits JSONL progress events containing progress_percent and, during builds, build_percent. Agents should surface that percentage in every long-running deploy update. services create performs a service read-back and patches dropped port/start_command config before returning; agents must stop before deployment creation if its verification.ok field is false.

Deploy into an existing project and service:

opendeploy deploy ./app --project <project-id> --service <service-id> --json

The current cold-start deploy step commands expose the agent-facing consent contract and fallback command list. The source step is executable; other mutation steps should use explicit resource commands until they return concrete next_action results. deploy apply --plan ... is a stop-gate dispatcher, not an opaque black-box deploy. Existing-service redeploy is available today. For advanced gaps, opendeploy api get|post|put|patch is available as a redacted OpenDeploy-only escape hatch; it deliberately does not expose DELETE.

Safety Model

• Credentials are stored under ~/.opendeploy/ with file mode 0600.
• Responses are redacted by default. Env containers keep key names and redact every value; other fields redact sensitive names only. Pass --show-secrets only when you explicitly need raw secret values.
• Destructive commands such as projects delete, services delete, and domains delete should not be run by agents without explicit user approval.
• Anonymous guest deploy credentials are quota-limited and intended for the first-deploy flow before account binding.

Documentation

• CLI usage
• CLI design

License

MIT