Reference

CLI commands

astrodock drives an Astrodock platform from an app repo: create the app, set secrets, deploy, and watch the result. This is the complete command reference.

Installing & aliasing the CLI

The astrodock command lives in the repo you cloned. Install dependencies once, then add a shortcut so you can call it from anywhere:

# from the astrodock repo folder
npm install

# add a handy alias (adjust the path to where you cloned it)
alias astrodock="node $(pwd)/packages/cli/bin/astrodock.js"

# check it
astrodock help

Tip

Add the alias line to your ~/.zshrc or ~/.bashrc to make it permanent. There's also a shorter alias: adock.

The two environment variables

The CLI reads exactly two variables for every command (except help):

Variable	What it is
`ASTRODOCK_URL`	Base URL of your admin host, e.g. `https://admin.example.com` (or `http://admin.localhost` locally). Required.
`ASTRODOCK_TOKEN`	A scoped API token (`tk_…`) or an admin JWT. Sent as a bearer token.

export ASTRODOCK_URL="https://admin.example.com"
export ASTRODOCK_TOKEN="tk_..."

How the slug is resolved

Most commands take an optional slug. If you omit it, the CLI reads slug from the app.json in the current directory (or the file you pass with --file). Run from your app folder and you rarely need to type the slug.

Synopsis

astrodock <command> [options]

  apply [--file app.json] [--prune]            Create/update the app, connect repo, provision
  deploy [slug] [--local]                      Trigger a deploy (--local uploads the working dir)
  deploy:watch [slug] [--local] [--id <id>]     Trigger (or attach to) a deploy and stream its log
  status [slug]                                Show the app's process status
  logs [slug] [--lines N]                      Print recent app logs
  set-secret <KEY> [value] [slug]              Set an env var value (stdin if value omitted)
  apps                                         List apps
  pages push <dir|file> [options]              Publish a document / bundle / file share to Pages
  pages list                                   List pages
  pages rm <pageId>                            Delete a page
  help                                         Show help

`apply`

Synopsis: astrodock apply [--file app.json] [--prune]

Reads app.json, validates it, and reconciles the platform to match: creates the app if the slug is new (otherwise updates it), connects the repo (creating the webhook), and provisions resources and routing — in one pass. It's additive and non-destructive, and it never prints secret values.

Option	Effect
`--file <path>`	Read the manifest from this path instead of `./app.json`.
`--prune`	Allow removing platform state (e.g. user-added env vars) that the manifest no longer mentions. Without it, `apply` never deletes them.

On success it reports whether the app was created or updated, prints a one-time app secret if one was generated (auth = platform), notes whether the repo was connected, and lists provisioning results:

$ astrodock apply
Created "starter" (starter.<domain>)
  app secret (shown once): as_...
  repo connected (webhook created)
  · internal database provisioned
  · routing configured

If validation fails

apply validates app.json against the schema first. An invalid manifest is reported with the exact problems and nothing is changed.

`deploy`

Synopsis: astrodock deploy [slug] [--local]

Triggers a deploy and returns immediately with the new deployment id (it does not stream — use deploy:watch for that). By default the runner deploys from the connected Git repo.

Option	Effect
`--local`	Tar the current working directory and upload it as the deploy source — no GitHub required. Heavy/secret paths (`node_modules`, `.git`, `dist`, `.env`, `.env.local`, `.DS_Store`) are excluded from the upload.

$ astrodock deploy
Deploy triggered for "starter" (deployment 42)

$ astrodock deploy --local
Uploading 12 KB for "starter"…
Local deploy triggered for "starter" (deployment 43)

Deploys can be blocked

If any required declared var, or an external-mode resource credential, has no value, the deploy is rejected before any build runs. The CLI prints exactly what's missing and exits non-zero — set the values with set-secret, then redeploy.

`deploy:watch`

Synopsis: astrodock deploy:watch [slug] [--local] [--id <id>]

The one to use day to day. It triggers a deploy and then streams the deploy log until the deployment reaches a terminal state — success or failed — exiting 0 on success and non-zero on failure. This is how you (or an agent) confirm a launch actually succeeded.

Option	Effect
`--local`	Same as `deploy --local`: upload the working dir instead of deploying from Git.
`--id <id>`	Attach to an existing deployment and stream its log, instead of triggering a new one.

$ astrodock deploy:watch --local
Uploading 12 KB for "starter"…
Local deploy triggered for "starter" (deployment 44)
[…] Installing server deps…
[…] Building frontend (npm run build)…
[…] Health probe: app is responding
[…] Deploy complete

✓ deploy success (a1b2c3d)

`status`

Synopsis: astrodock status [slug]

Prints the app's process status as JSON (whatever the platform reports for the running process or container).

$ astrodock status starter
{
  "slug": "starter",
  "status": "online",
  ...
}

`logs`

Synopsis: astrodock logs [slug] [--lines N]

Prints recent log output for the running app.

Option	Effect
`--lines N`	How many recent lines to fetch. Defaults to `100`.

$ astrodock logs --lines 200

`set-secret`

Synopsis: astrodock set-secret <KEY> [value] [slug]

Sets the value of an env var (typically a declared secret) on an app. The value can be passed as the second argument or piped via stdin if you omit it — handy for keeping secrets out of your shell history. The optional third argument is the slug (otherwise resolved from app.json).

# value as an argument
astrodock set-secret OPENAI_API_KEY sk-...

# value from stdin (no value argument) — never appears in shell history
printf '%s' "$MY_SECRET" | astrodock set-secret OPENAI_API_KEY

# explicit slug as the third positional
astrodock set-secret OPENAI_API_KEY sk-... starter

stdin vs argument

If you don't pass a value, the CLI reads it from stdin (when piped). If neither a value nor piped input is provided, it errors rather than setting an empty value.

`apps`

Synopsis: astrodock apps

Lists the apps the token can see, one per line: slug, subdomain, runtime type, database and storage modes, and whether the app is provisioned.

$ astrodock apps
starter              starter          node    db:none storage:none provisioned
invoices             invoices         node    db:internal storage:internal provisioned

`pages`

Synopsis: astrodock pages <push|list|rm> …

Publish and manage Pages — documents, static bundles, and file shares. Needs a token with the pages scope. push takes a folder (nested paths preserved) or a single file; --page-id updates an existing page instead of creating one.

$ astrodock pages push ./build --title "Q3 Dashboard"
Published 3 files to page "k3v9x2mqa7f1".
  URL:     https://pages.example.com/k3v9x2mqa7f1/

$ astrodock pages push ./build --page-id k3v9x2mqa7f1   # update in place
$ astrodock pages list
$ astrodock pages rm k3v9x2mqa7f1

Options: --title, --access public|passkey|platform, --generate-passkey / --passkey K, --data shared|per-user, --entry FILE, --page-id ID, --quiet. Full walkthrough: Publishing a page.

`help`

Synopsis: astrodock help (also the default with no command, or with --help)

Prints usage — the command list and the two environment variables. It's the only command that doesn't need ASTRODOCK_URL / ASTRODOCK_TOKEN set.

Walk the whole loop once: Deploy your first app
Set values for declared secrets and resources: Secrets & env vars
Create the token the CLI uses: API tokens

CLI commands

Installing & aliasing the CLI

The two environment variables

Synopsis

apply

deploy

deploy:watch

status

logs

set-secret

apps

pages

help

Related

`apply`

`deploy`

`deploy:watch`

`status`

`logs`

`set-secret`

`apps`

`pages`

`help`