Reference
CLI reference
codaracloud drives the platform from a terminal. It talks only to the HTTP API — it never needs cluster credentials.
Installing
The installers download a prebuilt binary for your platform and verify it against the SHA-256 published in the /v1/cli/manifest release manifest before installing anything. Neither one uses sudo or administrator rights.
macOS and Linux
$ curl -fsSL https://console.codaracloud.com/v1/cli/install.sh | shWindows PowerShell
irm https://console.codaracloud.com/v1/cli/install.ps1 | iexmacOS and Linux install into ~/.local/bin; set CODARA_INSTALL_DIR to pick another directory. Windows installs under %LOCALAPPDATA% and adds it to your user PATH. If you have an older codara or paasctl binary on your PATH from a previous release, remove it — the command was renamed to codaracloud.
Staying current
The CLI updates itself. At most once a day, a command run in a terminal installs a newer signed release, verified the same way as the installers, and prints one line saying so; the next run uses it. It never does this when output is not a terminal or when CI is set. Set CODARA_NO_AUTO_UPDATE=1 to turn it off; the older CODARA_NO_UPDATE_CHECK=1 still works too.
bash
$ codaracloud update # install the published release now (alias: upgrade)$ codaracloud update --check # only report whether one is newerBuilding from source
With a repository checkout and a recent Go toolchain:
bash
$ cd cli$ make build# then put the resulting binary on your PATH$ codaracloud versionShell completion
bash
$ codaracloud completion zsh > "${fpath[1]}/_codaracloud"$ codaracloud completion bash > /etc/bash_completion.d/codaracloudAuthenticating
bash
$ codaracloud login # approve in your browser$ codaracloud whoami # confirm who you are$ codaracloud logoutlogin prints a code and opens console.codaracloud.com/auth/cli, where you approve it with your Codara Cloud account (GitHub or Google sign-in). Set CODARA_NO_BROWSER=1 on a remote machine to only print the URL.
The credential is stored in your OS keyring, falling back to ~/.config/codara/config.yaml (mode 0600). It expires after 7 days — for unattended use, create an API token instead and pass it via CODARA_TOKEN. See Getting access.
Credentials are resolved in this order:
--token flag → $CODARA_TOKEN → OS keyring → config fileOnly login, logout, update (or upgrade), version, completion, help and open dashboard work without a credential.
Global flags
| Flag | Default | Purpose |
|---|---|---|
| -o, --output | table | Output format: table, json or yaml. |
| --api | console.codaracloud.com | API base URL. Also settable via CODARA_API. |
| --token | — | Use this credential instead of the stored one. |
| --debug | false | Verbose request logging. |
-o json returns a bare array
List commands emit the array of items directly, not an envelope — so
codaracloud apps list -o json | jq '.[].name' works as written.Scoping commands
Most commands accept --client, --project and --env. --client takes a workspace slug; the flag keeps the API’s older name for a workspace. Omitted, they fall back to your default workspace and the production environment.
Two sharp edges
- There is no persistent context — no
useorcontextcommand. Scope must be repeated on every invocation. - Scope flags are not universal.
apps get,env,domains,logsandmetricsaccept none at all and always resolve against the default workspace andproduction.jobsuses--environmentrather than--env.
Authentication and tokens
| Command | Description |
|---|---|
| login | Sign in with your Codara Cloud account in a browser. |
| logout | Clear the stored credential. |
| whoami | Show the current user and their workspaces. |
| token list | List your API tokens. |
| token create <name> | Create a token. The secret is printed once.--scopes --expires-in-days |
| token revoke <id> | Revoke a token. |
Apps
| Command | Description |
|---|---|
| apps list | List apps with status, URL and source.--client |
| apps get <app> | Show one app in detail. |
| apps create <name> | Create an app from a GitHub repository. --project is required unless the workspace has exactly one project. Note --env-slug for the environment — --env on this command carries environment variables. --dormant writes zero replicas and a manual-only sleep policy atomically, so no placeholder pod starts before configuration is complete.--client --project --env-slug --repo --branch --dockerfile --root-directory --watch-path --build-arg --env --replicas --port --private --dormant --manual-deploys |
| apps update <app> | Change runtime, source or deployment policy. At least one flag required.--client --project --env --port --replicas --cpu --memory --autosize --pin-resources --branch --root-directory --dockerfile --watch-path --clear-watch-paths --build-arg --clear-build-args --auto-deploy --manual-deploys |
| apps delete <app> | Delete an app after explicit force confirmation. Its platform release history and app-owned runtime resources are removed with it.--client --project --env --force |
| apps image <app> <ref> | Deploy a new image reference, or re-pull the current one.--client --project --env |
| apps sleep <app> | Scale to zero now. |
| apps wake <app> | Scale back up now. |
| apps autosleep <app> | Configure automatic sleeping.--enabled / --disabled --mode --idle-after --wake-on-http --min-when-awake |
| apps registry status <app> | Show whether private registry credentials are set.--client --project --env |
| apps registry set <app> | Set or rotate registry credentials. Password is read from stdin only.--client --project --env --username --password-stdin --server |
| apps registry remove <app> | Remove registry credentials.--client --project --env --confirm |
| apps connections list <app> | List databases connected to the app.--client --env |
| apps connections add <app> <db> | Connect a database and inject its credentials.--client --env --as --keys |
| apps connections rm <app> <db> | Disconnect a database.--client --env |
apps create does not start the first build
It creates the app pointing at a placeholder image. Follow it with
codaracloud deploy <app> --source, or use the console’s deploy wizard, which creates the app and starts its first build in one step.Deploying
| Command | Description |
|---|---|
| deploy <app> | Restart the current image, or build a source revision when one of the flags is given.--client --project --env --source --branch --commit |
| deploys list <app> | Deploy history, newest first.--client --project --env |
| deploys cancel <app> <id> | Cancel a build before it is promoted.--client --project --env --confirm |
| rollback <app> | Re-release an earlier deploy’s image: one of the app’s 10 most recent successful deploys, while its image exists.--client --project --env --to-deploy |
| promote <app> | Promote a release into another environment without rebuilding.--client --project --from-deploy --from-env --to-env |
deploy alone does not build
Without
--source, --branch or --commit, deploy only restarts the running image.Configuration
| Command | Description |
|---|---|
| env list <app> | List variables with masked values. |
| env get <app> <key> | Reveal one value. Audit-logged. |
| env set <app> KEY=VAL… | Set variables, or bulk-import a .env file.--from-file |
| env unset <app> <key>… | Remove variables. |
| env export <app> | Dump every value in .env format. Audit-logged. |
| shared-vars list | Environment-wide variables.--client --project --env |
| shared-vars get <key> | Reveal one shared value.--client --project --env |
| shared-vars set KEY=VAL… | Set shared values and their service bindings.--client --project --env --service --all-services |
| shared-vars bind <key> | Change which services receive a shared value.--client --project --env --service --all-services --clear |
| shared-vars unset <key>… | Delete shared values.--client --project --env |
| shared-vars reconcile | Retry projection after a partial failure.--client --project --env |
Databases
| Command | Description |
|---|---|
| databases list | List databases.--client --project --env --all |
| databases create <name> | Provision a database.--client --project --env --engine/--kind --tier --isolation --region --version --storage-size --pooler-transaction |
| databases connection <name> | Show connection details, masked by default.--client --project --env --reveal --url-only |
| databases proxy <name> | Open a local tunnel through the platform.--client --project --env --local-port |
| databases connect <name> | Print a port-forward recipe (requires cluster access to run).--client --project --env |
| databases upgrade <name> | Change tier, replicas, storage or pooling.--client --project --env --tier --replicas --storage-size --pooler-transaction --no-pooler-transaction |
| databases backup <name> | Take a backup now (PostgreSQL and dedicated Redis).--client --project --env --wait |
| databases restore <name> | Restore a backup into a new database.--client --project --env --from --as |
| databases delete <name> | Delete a database.--client --project --env --confirm |
Storage
| Command | Description |
|---|---|
| volumes list <app> | Attached disks and detached retained data.--client --project --env --json |
| volumes purge <app> <name> | Permanently delete a retained disk after exact-name confirmation.--confirm --client --project --env |
| volumes add <app> | Attach a persistent volume.--client --project --env --name --mount --size --storage-class |
| volumes grow <app> <name> | Grow a volume. Cannot shrink.--client --project --env --size |
| volumes remove <app> <name> | Detach a volume, preserving the data.--client --project --env |
Domains, logs and metrics
| Command | Description |
|---|---|
| domains list <app> | Hostnames attached to an app. |
| domains add <app> <host> | Attach a hostname. |
| domains remove <app> <host> | Detach a hostname. |
| logs <app> | Recent runtime output. --follow polls every 2 seconds.-f/--follow --tail |
| metrics <app> | CPU, memory, replicas and restarts.--window |
| open <app|dashboard> | Open in your browser. |
Workspaces, projects and jobs
| Command | Description |
|---|---|
| clients list | List workspaces. workspaces is an alias for clients. |
| clients create <slug> | Create an empty workspace.--contact-email --contact-name |
| projects create <project> | Create a project and its production environment.--client --name --description |
| clients edit <slug> | Update contact details.--name --contact-email --contact-name --notes |
| projects list | List a workspace’s projects.--client |
| projects update <project> | Rename a project or change its preview policy.--client --name --description --automatic-previews --preview-source |
| projects inventory <project> | The deletion checklist: every app (with its volume data), database, job, bucket and retained storage still inside, with the command that removes each.--client |
| projects delete <project> | Delete a project and its environments. Prints the checklist and refuses while anything remains — deletion is bottom-up and never cascades data.--client --confirm <project> |
| jobs list | List jobs.--client --project --environment |
| jobs get <job> | Show one job.--client --project --environment |
| jobs create <name> | Create a one-shot job, or a scheduled one with --schedule.--client --project --environment --image --command --arg --schedule --secret-file --egress-allow --cpu --memory |
| jobs rerun <job> | Run a saved job again, keeping earlier history.--client --project --environment --secret-file |
| jobs stop <job> | Stop a running one-shot job.--client --project --environment --wait |
| jobs delete <job> | Delete a job and its retained run.--client --project --environment --yes |
| jobs image <job> <reference> | Change the OCI image used by future scheduled runs.--client --project --environment |
| jobs logs <job> | Retained job output.--client --project --environment --tail |
Staff-only commands
cost, usage and the clients spend-cap and invoice commands are for Codara staff. The platform refuses them for customer accounts, so they are not listed here. Your plan and invoices are under Settings → Billing.Things without a dedicated command
codaracloud api <METHOD> </v1/path> makes a raw, authenticated API call for anything not wrapped in a command, such as buckets and build logs. To import data into a database, open a local tunnel with codaracloud databases proxy <name> and use your usual client against it. A domain’s DNS and certificate status is shown in the console.
Environment variables
| Variable | Effect |
|---|---|
| CODARA_TOKEN | Credential to use. |
| CODARA_API | API base URL. |
| CODARA_CONFIG | Path to the config file. |
| CODARA_NO_KEYRING | Skip the OS keyring and use the config file. |
| CODARA_NO_BROWSER | Never try to open a browser. |
| CODARA_NO_AUTO_UPDATE | Set to 1 to turn off automatic updates. |
Failed writes are not retried
Read requests retry automatically on transport errors; creates, updates and deletes do not. If one of those fails with a network error, check the current state before running it again.
Last updated