api and utilities

anycloud api

Manage the active API target:

anycloud api serve [options]
anycloud api list [--json]
anycloud api use [target]
anycloud api info
anycloud api update
anycloud api start [options]
anycloud api stop
anycloud api status
anycloud api logs [-f]
anycloud api access add <github-user>
anycloud api access remove <github-user-or-id>
anycloud api access list [--json]

Option	Description
--use	Make a new hosted API the active target
--checkpoint-bucket NAME	Existing user-owned bucket required for hosted API state
--checkpoint-storage-credentials NAME	Separate credential for the hosted API state bucket
--checkpoint-storage-region REGION	Hosted API state bucket region
--json	JSON output for API target or access lists
--port PORT	Local API port; default 8080
--version VERSION	API image version; defaults to the CLI version
-f, --follow	Follow local API logs

The default API URL is http://localhost:8080. api use persists a target in ~/.anycloud/api-url; API_URL is a one-command override. api use local saves the default local target. With no target in a TTY, api use opens a picker of healthy compatible APIs.

The local API binds 127.0.0.1.

api serve stores its SQLite database and cipher key in /mnt/checkpoint. Create a dedicated bucket first, then pass its name:

anycloud bucket create my-api-state \
  --credentials my-aws \
  --region us-east-1

anycloud api serve \
  --credentials my-aws \
  --vm-type t3.small \
  --checkpoint-bucket my-api-state

Creation, upgrades, and termination validate the same stored bucket before the generic Service checkpoint lifecycle runs. Anycloud never creates, recreates, or deletes it; delete it manually only when its state is no longer needed. Use one dedicated bucket per hosted API. Hosted APIs require a selected compute credential. That identity must have read-write access to the state bucket unless --checkpoint-storage-credentials selects a separate AWS identity. Use the separate identity for compute providers without compatible object storage, and pass --checkpoint-storage-region with it. The hosted API is the only Service allowed to use separate checkpoint credentials. See Buckets for sync and crash-consistency tradeoffs.

Update the API control chain

First update the CLI, then reconcile the API control chain:

anycloud update
anycloud api update

api update takes no arguments. It updates or starts the local API on ghcr.io/anycloud-sh/api:<installed-cli-version>. If the active API is hosted, the command then finds that hosted deployment in the local API database and queues its replacement through the refreshed local API. The public URL and retained checkpoint state are preserved while the backing VM is replaced.

The active API selection is not changed. A hosted URL that is absent from the local API database is rejected because its manager cannot be established. When a stopped active local API has a saved loopback URL with a custom port, api update starts it again on that port. With a hosted API active and no local container running, the local manager starts on the default port 8080.

Hosted APIs created without a retained checkpoint bucket cannot be upgraded safely and must be redeployed with anycloud api serve.

Give someone access

Anyone with access to a hosted API can share it with more GitHub accounts:

anycloud api use https://YOUR-HOSTED-API
anycloud api access add octocat
anycloud api access remove octocat
anycloud api access list

add resolves the supplied GitHub username to an immutable GitHub account ID and accepts individual user accounts only, not organizations. remove accepts either a username from the current access list or its displayed immutable ID. Access commands operate on the active API and are unavailable on a local API.

Added users authenticate normally with anycloud login and become equal peers: they share the hosted API's workloads, credentials, secrets, spend controls, and read-only database inspection. Any of them can operate on another creator's workload when its type and state support the requested command, and can add or remove non-owner users. Removing access does not stop existing workloads; remaining members can review them with anycloud list --user <github-user-or-id> and terminate them when needed. anycloud list covers everyone's deployments and names each creator whenever the result includes another account's work, including a result containing only that teammate's deployments. See Hosted APIs for the complete setup, lifecycle, and trust model.

anycloud login

anycloud login

Authenticate with GitHub OAuth for identity, private GHCR pulls, and Git code sync. When Docker is installed, the command also authenticates the local Docker CLI to GHCR for pushes.

anycloud update

anycloud update

Installer-script installations update from get.anycloud.sh; Homebrew installations update through Homebrew. A running local API is restarted when its image is stale relative to the installed CLI.

anycloud docs

anycloud docs [--all] [--url]

Option	Description
--all	Full Markdown corpus from llms-full.txt
--url	Print the source URL instead of fetching

The default prints the short llms.txt index.

anycloud db query

Run read-only SQL against the active API database:

anycloud db query "<sql>" [--json]

Only SELECT, WITH, EXPLAIN, and PRAGMA are allowed; writes are refused at the SQLite engine. Results stop at 10,000 rows. JSON is:

{ "rows": [], "rowCount": 0, "truncated": false }

anycloud db schema

anycloud db schema [table] [--json]

With no table, list all user tables and views. With a table, return its columns, foreign keys, and indexes. Agents should inspect the JSON schema before constructing an ad-hoc query.