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 validateOr install it globally to get a cosmoner command:
npm install -g @cosmoner/cliIt 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_KEYto a key you created, andCOSMONER_PROJECT_IDto 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:
--project <slug or id>on the command.COSMONER_PROJECT_IDin the environment.- 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 oncecosmoner 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:
| Code | Meaning |
|---|---|
0 | Success. |
1 | The operation failed — a file did not validate, a deploy failed, the API refused a request. |
2 | The 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 scriptsReading
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
| Product | Verbs |
|---|---|
apps | create, update, resize, delete, and sizes and regions to choose from |
servers | create, update (rename), start, stop, reboot, delete, and sizes, regions and images |
databases | create, rotate-password (shared databases), delete, and sizes |
redis | create, delete, and plans and regions |
buckets | create, delete |
registries | create, delete, and providers |
hosting | create, delete, and plans |
domains | create (a domain you own), verify, delete |
email | create (set a domain up for sending), verify, credentials create|delete, delete |
iam | create (an access key for buckets, the registry or both), delete |
ssh-keys | create (from your public key), generate, delete |
webhooks | create, update, test, rotate-secret, delete |
projects | update (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-1Confirmations
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:
| Command | Prints |
|---|---|
cosmoner iam create | An access key ID and its secret access key. |
cosmoner email credentials create | An SMTP username and password. |
cosmoner databases rotate-password | A shared database's new password and connection string. |
cosmoner ssh-keys generate | A private key — or, with --out <file>, writes it to a file instead. |
cosmoner webhooks create / rotate-secret | The 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 warningWith 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 | |
|---|---|
--strict | Fail on warnings too, such as an unknown key. |
--format text|json|github | github annotates findings on the pull request diff. |
--quiet | Report through the exit code only. |
# GitHub Actions
- name: Validate deployment file
run: npx @cosmoner/cli validate --strict --format githubOther file commands
| Command | What it does |
|---|---|
cosmoner init | Writes a starter .cosmoner/deployment.yaml, with comments on the fields you are most likely to set. --type static for a static site. |
cosmoner fmt | Rewrites the file in canonical field order and adds a $schema header for editor completion. Comments are kept. --check exits 1 instead of writing. |
cosmoner schema | Prints the JSON Schema for the file. --url prints its published URL. |
cosmoner agents | Adds 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 v2Deploying web (tag v2)
PENDING
DEPLOYING
✓ web is live on registry.cosmoner.com/acme/web:v2 after 41sDeploys 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-wait | Return 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|json | json 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 --deleteUploading dist to my-site:/my-site.cosmoner.com/public_html (42 files, 1.3 MB)
✓ Uploaded 42 files (1.3 MB), removed 3 in 6sUploads 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. |
--delete | Remove what is on the site but not in the directory. |
--dry-run | List 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:PfqYSl1pbMjfMKAbcmjzGZ0t1kpuCZ2mtymdyLu9HwASecrets and variables
echo "$DB_PASSWORD" | cosmoner secrets set DB_PASSWORD --environment production
cosmoner variables set LOG_LEVEL --value debug
cosmoner secrets listset 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|json | json 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.pdfget 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.