Cosmoner Docs
SDKs

CLI

The cosmoner command line tool — read and manage everything in a project, validate deployment files, deploy image apps, upload to web hosting, and manage secrets from a terminal, CI or a coding agent.

@cosmoner/cli is built on the JavaScript SDK and gives the most common pipeline steps a one-line command. Run it with npx, with nothing to install:

npx @cosmoner/cli validate

Or install it globally to get a cosmoner command:

npm install -g @cosmoner/cli

It is useful in any repository, not only JavaScript ones. A deployment file describes a deployment, not a Node project, so the CLI works the same in a Go or Rust repository.

Credentials

The file commands — validate, fmt, init, schema and agents — work offline. They need no account, no API key and no network.

Everything else calls the API, and takes its credential from one of two places:

  • On your own machine, run cosmoner login. It opens your browser, where you check the code and approve. The CLI is then signed in to your account and acts as you, in every project you are a member of, with your role in each. See Signing In With the CLI.
  • In CI, set COSMONER_API_KEY to a key you created, and COSMONER_PROJECT_ID to its project. The environment variable always wins over a saved login.

There is deliberately no flag for passing a key: a flag ends up in shell history and CI logs.

Choosing a project

A login reaches all of your projects, so each command needs to know which one to act on. It takes the first of:

  1. --project <slug or id> on the command.
  2. COSMONER_PROJECT_ID in the environment.
  3. The default you set with cosmoner use.
cosmoner use acme-web        # set the default project
cosmoner use                 # show it
cosmoner deploy web --tag v2 --project acme-api   # just this once

cosmoner whoami shows who the CLI is signed in as, when the login expires, and the default project. cosmoner logout signs the machine out.

Exit codes

Every command uses the same three codes, so a CI step can tell a broken deploy from a typo in its own command line:

CodeMeaning
0Success.
1The operation failed — a file did not validate, a deploy failed, the API refused a request.
2The command itself was wrong — an unknown option, an unreadable path — or a confirmation was needed and nobody could give it.

Manage resources

Each product a project has is a command: apps, servers, databases, redis, buckets, registries, hosting, domains, email, iam, ssh-keys, webhooks, members and projects. They share the same verbs, and cosmoner <product> --help lists every verb a product has, with its options and the API-key scope it needs.

cosmoner get --all                   # everything in the project
cosmoner apps get                    # every app
cosmoner apps get web                # one app, by name or id
cosmoner servers get --format json   # the API's own objects, for scripts

Reading

get with no name lists everything; with a name or id it shows that one item. cosmoner get --all reads every product at once; a product the credential cannot read is reported with the reason rather than failing the whole command. --format json prints the API's objects, an array for a listing and one object for an item.

Credentials are never printed by a read — passwords, connection strings and keys show as [hidden]. cosmoner apps logs <app> --type run|build reads an app's recent log lines.

Changing

ProductVerbs
appscreate, update, resize, delete, and sizes and regions to choose from
serverscreate, update (rename), start, stop, reboot, delete, and sizes, regions and images
databasescreate, rotate-password (shared databases), delete, and sizes
rediscreate, delete, and plans and regions
bucketscreate, delete
registriescreate, delete, and providers
hostingcreate, delete, and plans
domainscreate (a domain you own), verify, delete
emailcreate (set a domain up for sending), verify, credentials create|delete, delete
iamcreate (an access key for buckets, the registry or both), delete
ssh-keyscreate (from your public key), generate, delete
webhookscreate, update, test, rotate-secret, delete
projectsupdate (rename), delete

members is read-only from the CLI.

cosmoner servers sizes                       # what can be ordered, with prices
cosmoner servers create web-1 --size <size> --region <region>
cosmoner servers reboot web-1
cosmoner servers delete web-1

Confirmations

A change that costs money or cannot be undone asks first: creating a paid resource or resizing one, every delete, stopping or rebooting a server, rotating a webhook's secret or a database's password, and verifying an email domain when that starts billing a plan with a monthly price. A paid order shows its price before it asks.

$ cosmoner redis delete cache
This deletes redis "cache". Its data goes with it, and its billing stops. It cannot be undone.
Delete redis "cache"? [y/N]

--yes answers in advance, for scripts. Without a terminal and without --yes — CI, or a coding agent's shell — the command prints what it would do, changes nothing and exits 2, so an agent has to show you the change and get your approval before it adds --yes.

Credentials printed once

A credential the API generates exists only in the response that creates it, so these commands print it once and nothing prints it again:

CommandPrints
cosmoner iam createAn access key ID and its secret access key.
cosmoner email credentials createAn SMTP username and password.
cosmoner databases rotate-passwordA shared database's new password and connection string.
cosmoner ssh-keys generateA private key — or, with --out <file>, writes it to a file instead.
cosmoner webhooks create / rotate-secretThe signing secret.

Save it straight away, or store it with cosmoner secrets set.

Coding agents

cosmoner agents writes a short section into AGENTS.md telling coding agents which commands exist, which ones need your approval, and how to handle credentials. The section is generated by the CLI that writes it, so after upgrading the CLI run cosmoner agents again; the CLI reminds you, at most once a day, when the section in the current directory is out of date.

Validate a deployment file

cosmoner validate
.cosmoner/deployment.yaml
  2:11  error    Service names must be lowercase letters, numbers, or hyphens, and start with a letter or number  services.0.name
  4:18  error    Static sites cannot define a run_command  services.0.run_command
  5:11  warning  Unknown field "prot" — it will be ignored  services.0.prot

2 errors, 1 warning

With no argument, it finds the file the way the platform does. It runs the same check as the SDK validators and adds the line and column of each finding.

Option
--strictFail on warnings too, such as an unknown key.
--format text|json|githubgithub annotates findings on the pull request diff.
--quietReport through the exit code only.
# GitHub Actions
- name: Validate deployment file
  run: npx @cosmoner/cli validate --strict --format github

Other file commands

CommandWhat it does
cosmoner initWrites a starter .cosmoner/deployment.yaml, with comments on the fields you are most likely to set. --type static for a static site.
cosmoner fmtRewrites the file in canonical field order and adds a $schema header for editor completion. Comments are kept. --check exits 1 instead of writing.
cosmoner schemaPrints the JSON Schema for the file. --url prints its published URL.
cosmoner agentsAdds a short "Deploying to Cosmoner" section to AGENTS.md, so coding agents validate, deploy and handle secrets the way the CLI expects. Safe to re-run.

Deploy an image app

cosmoner deploy web --tag v2
Deploying web (tag v2)
  PENDING
  DEPLOYING
✓ web is live on registry.cosmoner.com/acme/web:v2 after 41s

Deploys an image app — one that runs an image from a Cosmoner registry — and waits for the rollout. web is the app's name or id. The key needs apps:read and apps:write.

Option
--tag <tag>Deploy this tag. A commit SHA pushed as a tag goes here.
--digest <digest>Deploy this exact image.
--no-waitReturn as soon as the deploy is accepted.
--timeout <seconds>How long to wait. Defaults to 600. A timeout stops the wait, not the deploy.
--project <slug|id>Defaults to COSMONER_PROJECT_ID, then the project set with cosmoner use.
--format text|jsonjson prints the app and the final deployment.

With neither --tag nor --digest, the image the app already names is pulled again.

# GitHub Actions
- name: Deploy
  run: npx @cosmoner/cli deploy web --tag ${{ github.sha }}
  env:
    COSMONER_API_KEY: ${{ secrets.COSMONER_API_KEY }}
    COSMONER_PROJECT_ID: ${{ vars.COSMONER_PROJECT_ID }}

Upload to a web hosting site

cosmoner upload my-site dist --delete
Uploading dist to my-site:/my-site.cosmoner.com/public_html (42 files, 1.3 MB)
✓ Uploaded 42 files (1.3 MB), removed 3 in 6s

Uploads a directory to a web hosting site over SFTP. The SFTP login is fetched with the API key, so CI needs no password of its own. The key needs hosting:read.

Existing files are overwritten. Files on the site that are not in the directory are left alone unless you pass --delete. An empty directory is refused, since it is usually a build that produced nothing.

Option
--remote <path>Folder to upload into. Defaults to the one the site's own hostname serves.
--deleteRemove what is on the site but not in the directory.
--dry-runList what would change without changing anything.
--host-key <sha256>Refuse a server with a different host key. Defaults to COSMONER_SFTP_HOST_KEY.

Pin the host key so the password is never sent to a server pretending to be ours. The gateway's key is:

SHA256:PfqYSl1pbMjfMKAbcmjzGZ0t1kpuCZ2mtymdyLu9HwA
# GitHub Actions
- name: Upload site
  run: npx @cosmoner/cli upload my-site dist --delete
  env:
    COSMONER_API_KEY: ${{ secrets.COSMONER_API_KEY }}
    COSMONER_PROJECT_ID: ${{ vars.COSMONER_PROJECT_ID }}
    COSMONER_SFTP_HOST_KEY: SHA256:PfqYSl1pbMjfMKAbcmjzGZ0t1kpuCZ2mtymdyLu9HwA

Secrets and variables

echo "$DB_PASSWORD" | cosmoner secrets set DB_PASSWORD --environment production
cosmoner variables set LOG_LEVEL --value debug
cosmoner secrets list

set creates a value, or replaces one that already exists with that name in that environment. rm removes it, and list shows what is there.

Option
--environment <env>default, development, staging or production. Defaults to default.
--value <value>The value, taken literally.
--from-file <path>Read the value from a file.
--description <text>Set alongside the value.
--format text|jsonjson output never includes a secret's value.

Pipe secret values in. A value passed with --value can be recovered from shell history and may be echoed by a CI runner. cosmoner secrets never prints a value back, for the same reason.

The key needs secrets:write or variables:write, and its owner must be an owner or admin of the project — see Secrets and Variables.

# GitHub Actions
- name: Set the database password
  run: echo "$DB_PASSWORD" | npx @cosmoner/cli secrets set DB_PASSWORD --environment production
  env:
    COSMONER_API_KEY: ${{ secrets.COSMONER_API_KEY }}
    COSMONER_PROJECT_ID: ${{ vars.COSMONER_PROJECT_ID }}
    DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

Invoices

cosmoner invoices reads the invoices issued to a project, newest first. It needs billing:read.

cosmoner invoices get                                    # the latest 25
cosmoner invoices get DB-0001                            # one, by number or id
cosmoner invoices export --from 2026-01-01 --to 2026-03-31 > q1.csv
cosmoner invoices download DB-0001                       # saves DB-0001.pdf

get narrows the list with --status, --from and --to, and shows up to 100 with --limit. export writes every matching invoice, up to 1,000, as CSV — the columns the control panel exports, plus a PDF link — or the API's objects with --format json. It is rate-limited, so use get for a quick look. download never overwrites a file; --out <file> picks another path.

On this page