CLI reference

The public CLI source and releases live at github.com/opencloud-ai/cli. OpenCloud skills pin an exact release instead of installing a moving branch.

Install the pinned release

The current release is v0.6.0 and requires Node.js 22 or newer:

OPENCLOUD_CLI_VERSION="v0.6.0"
OPENCLOUD_CLI_PACKAGE="opencloud-cli-0.6.0.tgz"
OPENCLOUD_CLI_DIR="$(mktemp -d)"

curl -fsSLo "$OPENCLOUD_CLI_DIR/$OPENCLOUD_CLI_PACKAGE" \
  "https://github.com/opencloud-ai/cli/releases/download/$OPENCLOUD_CLI_VERSION/$OPENCLOUD_CLI_PACKAGE"
curl -fsSLo "$OPENCLOUD_CLI_DIR/checksums.txt" \
  "https://github.com/opencloud-ai/cli/releases/download/$OPENCLOUD_CLI_VERSION/checksums.txt"

if command -v sha256sum >/dev/null 2>&1; then
  (cd "$OPENCLOUD_CLI_DIR" && sha256sum --check --ignore-missing checksums.txt)
else
  (cd "$OPENCLOUD_CLI_DIR" && shasum -a 256 --check checksums.txt)
fi

npm install --prefix "$OPENCLOUD_CLI_DIR" \
  --ignore-scripts --no-audit --no-fund \
  "$OPENCLOUD_CLI_DIR/$OPENCLOUD_CLI_PACKAGE"
OPENCLOUD_CLI="$OPENCLOUD_CLI_DIR/node_modules/.bin/opencloud"
test "$("$OPENCLOUD_CLI" --cli-version)" = "0.6.0"

Run commands from any directory:

"$OPENCLOUD_CLI" <command>

The CLI searches parent directories for the nearest protected session file. Run opencloud doctor for redacted identity, endpoint, CLI, and platform version diagnostics; it never prints the credential.

Passwordless onboarding

For a new app, no copied connection pack, owner UUID, or hand-picked domain is required:

"$OPENCLOUD_CLI" onboard \
  --email [email protected] \
  --name "Family tasks" \
  --visibility private

The API allocates <title>-<six random characters>.opencloud.ai atomically.

• A new email gets a provisional identity, first project, and 24-hour account grant immediately. The grant may create additional apps. OpenCloud sends a Resend confirmation email that expires after 24 hours.

• An existing email gets no project credential until its owner submits the confirmation form. Then run:

  "$OPENCLOUD_CLI" onboard-complete

The CLI writes the short-lived credential or pending completion secret to .opencloud/session.json, creates .opencloud/.gitignore, and applies file mode 0600. The CLI automatically uses this file for later commands. Never print, inspect, copy, or commit it. Override its location only when necessary with OPENCLOUD_SESSION_FILE or --session-file.

Existing deployments may still provide OPENCLOUD_API_URL and OPENCLOUD_TOKEN. OPENCLOUD_EDGE_URL is an optional transport adapter for non-browser CLI requests.

App

app list
app create --name <name> [--visibility <public|private>]
app get <app-id>
app sdk-inspect <app-id>
app origin <app-id>
app request <app-id> [path]
app verify <app-id>
app configure <app-id>

app verify starts and follows the authoritative server-side release gate. Legacy app smoke and app verify-ui commands remain local diagnostics only.

Development sessions

app dev start <directory>
app dev sync <directory>
app dev status [directory]
app dev request <directory> [path] [--method GET|HEAD]
app dev data <directory> <rest-path> [--method POST|PUT|PATCH|DELETE] [--body <json>]
app dev invoke <directory> <function-name> [--body <json>]
app dev requests [directory] [--limit <number>]
app dev receipts [directory] [--limit <number>]
app dev evidence [directory]
app dev verify [directory]
app dev promote [directory] [--idempotency-key <key>]
app dev stop [directory]

start and sync use the canonical bundler, synchronize changed and deleted draft files with optimistic guards, and reject a local/server artifact digest mismatch. Local .opencloud/dev.json stores only IDs and hashes.

The preview has a separate database schema and cannot access production data, secrets, Auth, Storage, Realtime, or cron. Dev Functions remain dormant until invoke or a deliberate preview interaction; requests returns correlated, redacted outcomes. data writes only to the dev REST schema. verify issues a receipt for the exact active revision. promote refuses any changed, stale, or unverified candidate, then follows deployment, verifies production, prints the live URL, and stops dev. Read the development guide before invoking Functions with possible external side effects.

Bundle and deployment

init <directory> [--app-id <uuid>] --version <version>
artifact-check <directory> [--expect-app-id <uuid>] [--max-files <count>]
validate <directory> [--write-archive <path>]
deploy <directory> --idempotency-key <key>
operation get <operation-id> --follow
deployment list <app-id>
deployment get <app-id> <deployment-id>
deployment rollback <app-id> <deployment-id>

After onboard, init infers the app ID from the secure session file.

Runtime verification

session verify <app-id>
verify <app-id> <verification-file>
cron history <app-id>
cron invoke <app-id> <cron-name>

Secrets and observability

The installed v0.6.0 release provides:

secret generate <app-id> <name>
secret entry-link <app-id> <name>
secret list <app-id>
logs <app-id>
metrics <app-id>
usage <app-id>

Use secret generate when OpenCloud can create the value. Use secret entry-link when a human must supply it; the one-time browser page keeps the value outside the agent conversation. The canonical CLI intentionally has no plaintext secret-import command.

CLI v0.6.0 also provides:

agent-feed <app-id> [--since <iso>]
alert-rule list <app-id>
alert-rule put <app-id> <rule-id> --name <name> --metric <metric> \
  --aggregation <sum|rate|latest|min|max|avg> \
  --operator <gt|gte|lt|lte|eq> --threshold <number> \
  --window <5m|15m|1h|24h>
alert-rule delete <app-id> <rule-id>

Use agent-feed for routine agent monitoring. Raw logs and metrics remain diagnostic surfaces. Alert rules can reference only metrics declared by the active deployment and do not accept PromQL or LogQL.

Backup

backup create <app-id>
backup list <app-id>
backup schedule <app-id> <daily|weekly|none>
backup restore <app-id> <backup-id>

Rollback and restore are destructive recovery actions. Do not use them as routine deployment tests.