Getting started with the CLI

Command

aoox

Auth

An aoox_… API token from the panel

Needs

Install script (no Node.js), or Node.js 22+ (npm)

Installing the CLI

On Linux or macOS, the install script sets up aoox with no Node.js required at all — the tarball bundles its own Node.js runtime:

curl -fsSL https://aoox.dev/install-cli.sh | sh

aoox --version

Installs to /usr/local/lib/aoox + /usr/local/bin/aoox (root/sudo), or ~/.local/lib/aoox without that access (then the script prints a note: sudo aoox install will not find a binary in ~/.local/bin, so re-run it with sudo sh or call sudo ~/.local/bin/aoox install). Running the same command again upgrades in place. Supports Linux (glibc — not Alpine/musl) and macOS, x64 and arm64.

npm install -g @hideandseeklab/aoox

aoox --version

The command is installed as aoox even though the package is named @hideandseeklab/aoox. To track main before it's released, install from source:

git clone https://github.com/hideandseeklab/aoox-cli.git
cd aoox-cli
npm install
npm run build
npm link          # makes the aoox command available globally

aoox --version

Installing aoox via aoox install

This command is different from the section above: aoox install doesn't connect to an existing panel — it installs its own panel (postgres + api + web) on a fresh Linux VPS, as an alternative to the manual steps in Installation. Run it as root, directly on the target server.

$ sudo aoox install
==> Detecting the server public IP
Install aoox in /opt/aoox and run docker compose up -d? (Y/n)
==> Running docker compose up -d
==> Waiting for the API to be ready

aoox is installed in /opt/aoox.
Open: http://203.0.113.10:3000
Create the first owner account at /setup.

sudo aoox install \
  --web-domain panel.example.com \
  --api-domain api.panel.example.com \
  --acme-email me@example.com \
  --admin-email me@example.com \
  --admin-name "Admin" \
  --admin-password "a-strong-password" \
  --yes

• Docker is installed automatically via get.docker.com if it isn't already present — asks for confirmation unless --yes is given.
• --web-domain and --api-domain require each other, and both need --acme-email for a Let's Encrypt certificate via the built-in proxy.
• Without --admin-email, create the owner account via /setup in the browser, same as a manual install.
• The default install folder is /opt/aoox (change it with --dir); an existing install in that folder is rejected unless --force is given.
• --force on an existing install backs up .env.dist and the compose files to <dir>/backups/<timestamp>/ and reuses the existing secrets and every existing value (only flags you pass replace values), so the data survives.
• Starting completely over needs all three of --force --new-secrets --wipe-data: it runs docker compose down -v for the existing stack (the database volume is deleted), generates new secrets, and requires you to type the install folder to confirm — --yes alone is not enough; non-interactively pass --confirm-wipe=/opt/aoox.--new-secrets or --wipe-data on their own are refused: new secrets cannot unlock the old database volume, which is what used to break the install.
• Secrets (JWT_SECRET, ENCRYPTION_KEY, the Postgres password) are generated at random and written to .env.dist with mode 0600 — no need for manual openssl rand.

Signing in to the panel

1. Create an API token in the panel

   Settings → API token: give it a name (e.g. my-laptop), pick an expiry, then copy the aoox_… token — it's only shown once. A token acts as its owner, with the same role — see Account security. The dialog that shows the token also has a copy-ready aoox login --url … --token … line.

2. Run aoox login

   $ aoox login
   Use the address you open the dashboard with: your panel domain (e.g. https://dashboard.example.com),
   or http://<server-IP>:3000 if no panel domain is set yet.
   ? Dashboard URL https://panel.example.com
   Looking for the panel... ok
   API token (aoox_…) ********
   Verifying token... ok
   Logged in as you@example.com (owner) at https://panel.example.com
   Token saved to /home/you/.config/aoox/config.json

   You only ever enter the dashboard address — the one you open in your browser, never the API address. The CLI reads the API address from the dashboard (/.well-known/aoox.json). You can leave out the scheme: a bare host is tried over https, then http, and a bare IP also on port 3000, so 203.0.113.10 works on a fresh install with no panel domain. If the dashboard does not advertise a public API address, the CLI assumes <same host>:3001 and says so. An API address given by an older script still works (with a one-line note).

   The token is asked for via a hidden prompt, not an argument, so it doesn't end up in shell history or the process list. Before saving, the CLI calls GET /auth/me — rejected credentials are never written to disk.

3. Confirm you're connected

   $ aoox whoami
   you@example.com · owner · Admin
   Panel: https://panel.example.com

   Add --json for script-friendly output; the plain text lines above are hidden automatically.

Which panel am I connected to?

Running aoox with no arguments lists the commands and, below them, where the CLI is connected. The dashboard and API addresses come from the saved login (no network); the registry line asks the panel for its default registry with a short timeout and never fails the command. aoox --help and aoox <command> --help are unchanged.

$ aoox
...
Connected to
  Dashboard  https://dashboard.example.com
  API        https://api.example.com
  Registry   registry.example.com (self-hosted)

$ aoox            # not logged in
Not connected — run: aoox login

If the registry cannot be checked you see Registry (could not check: panel unreachable); a localhost:… registry address gets a short warning to set a domain with aoox registry domain --set <host>.

Build & deploy from a local repo

aoox link connects a repo folder to a single application in the panel, then aoox deploy builds the image on your machine, pushes it to a registry, and triggers a deploy — following the log until it's done, just like the Deploy tab in the dashboard.

1. Link the folder to an application

   $ cd my-app-repo
   $ aoox link
   ? Select a project › shop
   ? Select an application › shop (shop)
   Linked: shop / shop (shop)
   Written to .aoox.json — safe to commit, contains no secrets.

   --project/--app skip the interactive picker — used in CI. The generated .aoox.json file contains no token, so it's safe to check in.

2. Deploy

   $ aoox deploy
   ==> Build localhost:5000/shop/shop:a1b2c3d
   ==> docker login localhost:5000
   ==> Push localhost:5000/shop/shop:a1b2c3d
   ==> Updating the application & triggering a deploy
   [building] Building localhost:5000/shop/shop:a1b2c3d from https://…
   ...
   Deployed: localhost:5000/shop/shop:a1b2c3d

   The build runs on your local Docker (docker build with --dockerfile/--context), then gets pushed to that application's registry — the self-hosted registry by default if there's more than one, or pick manually with --registry. The default tag is the git short SHA (+ -dirty if there are uncommitted changes); override it with --tag.

Variables (aoox env, aoox run)

aoox env reads and changes the environments of variable sets (the same ones as Variables in the dashboard) and manages which of them the linked application uses. aoox run starts a command with the variables the application gets at deploy time, without writing a file.

• A set environment is chosen with --set <slug> (short -s) and --env <name> (-e).
• Defaults: --set is the only set the application linked with aoox link uses (or the only set you can see); --env is the only environment of that set it links. With several candidates the command stops and lists them — it never guesses. There is no default environment name.
• --app <id> uses another application, and --stack <id> a compose stack, instead of the linked application.

$ aoox env list
backend  (Backend) · shared with shop, blog · your role: developer
  development             3 variables
  staging                 0 variables
  production (protected)  7 variables  used by 2

$ aoox env set API_URL=https://api.example.com GREETING="hello world" -s backend -e development
backend/development: added API_URL, GREETING (5 variables now)

$ aoox env list --set backend --env development            # names only, values masked
API_URL=••••••••
$ aoox env list --set backend --env development --reveal   # values (audited)
$ aoox env pull --set backend --env development            # writes ./.env (mode 0600)
$ aoox env unset OLD_KEY --set backend --env development
$ aoox run -- npm run dev                                  # the deployed app's variables (likely production)

What aoox run passes to the command

• By default it does what the panel does when it creates the container, as far as a terminal can: it reads every set environment the application links, in order (a later one wins on the same key), then puts the application's own env on top. Every read is audited. If any of them cannot be read (a protected environment, a viewer, a token scope), nothing is started.
• ${{vars.KEY}} is replaced by the merged set value of KEY, one level deep like the panel.
• ${{database.…}} and ${{secret.…}} references, and a ${{vars.KEY}} that no linked set defines, are left as written, with one warning naming those variables: only the panel resolves them at deploy time. Secrets synced from Infisical are not included (a warning says so).
• --set/--env instead use exactly one set environment: no links and no own env.
• --file .env.local goes on top of all of that: the order, lowest to highest, is your current environment, then aoox, then the file. The file is only read, and its references are not resolved.

$ aoox run -- node server.js
aoox  Injecting 9 variables into your process · Application "shop-web": shared/production < backend/production < own env

The count is what aoox adds or overrides, including --file; variables inherited from your shell are not counted. The line is coloured only on a terminal: NO_COLOR turns colour off, FORCE_COLOR forces it, and pipes and CI logs stay plain. --quiet (-q) hides the line, but warnings about references aoox cannot resolve are always printed.

Pull formats and push

$ aoox env pull --env staging                        # ./.env, the stored text with its comments
$ aoox env pull --format json                        # ./.env.json  {"KEY":"value"}
$ aoox env pull --format shell                       # ./.env.sh    export KEY='value'
$ aoox env pull --format json --file - | jq .PORT    # standard output only
$ eval "$(aoox env pull --format shell --file -)"    # load into the current shell

• --file - writes the data to standard output and nothing else there, so it can be piped or passed to eval. Notes (such as the one about ${{…}} references) go to standard error. In this mode there is no "file exists" check and no .gitignore warning, because no file is written.
• The shell format wraps each value in single quotes and writes a single quote inside a value as '\'', so spaces, $ and quotes survive eval. Without --file the file is .env, .env.json or .env.sh by format, always with mode 0600 where the OS supports it.

$ aoox env push --file .env.staging --set backend --env staging
Environment: backend/staging
  + added (1): NEW_FLAG
  ~ changed (1): API_URL
  - removed (1): OLD_KEY
  = unchanged: 6
Variables that are not in the file are removed: this replaces the whole environment.
? Replace "backend/staging" with the contents of .env.staging? (y/N)

• The file is checked before anything is sent. Refused: invalid names, an export prefix, trailing whitespace, duplicate names and ${{project.…}}. Quoted values (KEY="value") are accepted with a warning, because the panel stores the quotes as part of the value. Windows line endings and a leading BOM are normalised.
• push, promote and diff never print values. push and promote ask for confirmation; without a terminal (CI) they refuse unless you pass --yes. If someone else changed the environment in between, nothing is written (409), as with set.
• Every change is recorded as a version (see history and restore); restoring an old version is done in the dashboard.

How values are stored (quoting)

The panel keeps one environment as plain KEY=VALUE text, one variable per line. The key is everything before the first =; the value is everything after it, exactly as given. There is no quote or escape processing — not in the CLI, not in the panel, not when the value is put into the container — so the quotes you type are removed by your shell, and quotes that are part of the value stay part of it.

• Rejected before anything is sent: an invalid name (letters, digits and _, not starting with a digit), a value with a newline (one variable per line), and a value that ends with whitespace (the panel trims the end of each line).
• ${{vars.KEY}} and ${{database.<slug>.url}} references are stored and pulled as written; the panel resolves them when the container is created.
• Compose stacks read the resolved text through Docker Compose's own --env-file parser, which does strip quotes around a whole value. Avoid surrounding quotes in values used by stacks.

Editing at the same time

set, unset and push read the environment, change the text and save it back together with the version they read. If someone else saved in between (the dashboard, another terminal), the panel answers 409 and the CLI says that nothing was written — run the command again to apply your change on top of the latest version. The dashboard's editor does the same.

Who can do what

• Links: env link/unlink need the developer role in the application's project; adding or removing a link to a protected environment needs the project admin role. The set must be shared with the project.
• In CI create an API token and export AOOX_TOKEN/AOOX_URL. The token can be limited to some set environments (Settings → API token → the variables limit), e.g. backend/staging, backend/* or */development: other environments then answer 403. See API token scopes.
• A read-only token can still run aoox env pull, aoox env list --reveal and aoox run (reading changes nothing and is audited), but set, unset, push, promote, link and unlink are refused. Viewers can never read values, with or without a token.
• Every read of values is recorded in the audit log without the values. Reading is a request to the API, so an environment is never cached on disk by the CLI.
• Creating, sharing and deleting sets and environments is done in the dashboard by an instance owner or admin.

Local development

Run your app on your laptop with the variables of one set environment, without a .env file and without linking the folder. You only need to be signed in.

1. Install the CLI, create a narrow token, sign in

   $ npm i -g @hideandseeklab/aoox
   $ aoox login

   In the panel, Settings → API token → Create token: turn Read-only on and set Limit to variables to the environment you develop against, e.g. backend/development. A laptop token then cannot touch production. See API token scopes.

2. Put the command in package.json

   package.json

   "scripts": {
     "start:dev": "aoox run --set backend --env development -- nest start --watch"
   }

   Coming from Infisical? infisical run --env=dev -- … becomes aoox run --set <slug> --env development -- ….

3. Always pass --set and --env locally

   Without them you get the deployed app's variables

   aoox run -- … with no --set/--env needs a linked application and injects what its container gets at deploy: the application's linked set environments plus its own env. That is usually production, and changing the application's links in the panel would silently change what your laptop gets. With --set/--env exactly one environment is injected: no links, no own env.

4. What you see

   $ aoox run --set backend --env development -- nest start --watch
   aoox  Injecting 5 variables from backend/development (no links, no own env)

   • The line goes to standard error and is coloured only on a terminal (plain when piped or with NO_COLOR). --quiet (-q) hides it, never the warnings.
   • Fail closed: if the read is refused (bad token, no access, a protected environment, a token scope), the command is not started at all.
   • Variables live in the child process only; nothing is written to disk.

5. Tools that only read a file

   $ aoox env pull --set backend --env development --file .env

   The file is written with mode 0600 and never overwritten without --force. Make sure .env is in .gitignore; aoox warns when it is not.

6. Do you need aoox link?

   Not for local variables: --set/--env only need you to be signed in. You do need it for aoox deploy, for aoox run without flags, and for managing links with aoox env links/link/unlink. It writes .aoox.json (panel address, project and application ids and names, no secrets), which is safe to commit.

7. CI

   Skip aoox login and set AOOX_URL and AOOX_TOKEN (a masked CI variable) from a read-only token limited to the environment the job needs.

   $ AOOX_URL=https://panel.example.com aoox run --set backend --env development -- npm test

Limits

• ${{database.…}} and ${{secret.…}} references stay as written, with a warning: only the panel resolves them at deploy time. Point those variables at a local database in a local-only variable or --file.
• Secrets synced from Infisical are not included.
• If --set/--env are omitted and several candidates exist, the command stops and lists them; it never guesses.

Build & push images (aoox registry)

Two commands for getting an image into the registry without deploying it — handy when you want to pick the image later in the dashboard (New application → Ready-made image). Neither needs aoox link; they use your normal login (or --url/--token). The registry is the self-hosted one by default; pass --registry <id> to use another.

$ aoox registry build myapp:1.0.0
==> Build registry.example.com/myapp:1.0.0
...
Built registry.example.com/myapp:1.0.0
Next: aoox registry push myapp:1.0.0 (or build with --push next time)

$ aoox registry push myapp:1.0.0
==> docker login registry.example.com
==> Push registry.example.com/myapp:1.0.0
Pushed registry.example.com/myapp:1.0.0
Use it in the dashboard: New application → Ready-made image

build reads ./Dockerfile (-f/--dockerfile, --context) and names the image <registry host>/<name>:<version>. push only pushes an image that already exists locally and accepts the short name or the full one. To do both in one step, use aoox registry build myapp:1.0.0 --push. Names are lowercase.

You do not have to type everything. Leave out the version (aoox registry build myapp) or the whole argument (aoox registry build) and the CLI reads it from the project: the build context for build, the current folder for push. A typed name:version always wins. The first file found, in this order, supplies each value:

Values from a file that are unusable (a $(…) or ${…} variable, a dynamic version) are skipped and the next source is tried. Names are lowercased; a + in a version (build metadata, which tags cannot hold) becomes _. If HEAD is past the last git tag, nothing is guessed: tag the release, type name:version, or add --force to use the git describe form such as 1.4.2-3-gabc1234.

$ aoox registry build
==> Image web:1.4.2 (name and version from package.json)
? Build web:1.4.2? (Y/n/e)

Because a derived name or version can be wrong, the CLI asks before it does anything: Y continues, n stops, and e lets you type another name:version. --yes (-y) skips the question. Without a terminal, or when CI is set, it refuses and asks for name:version or --yes. A fully typed name:version never asks. If you forget to bump the version, the "already exists" check below still protects the registry, and says where to change it.

Changing the panel's domain

An alternative to Settings → Domain panel in the dashboard — good for provisioning scripts. See Domain for the panel for the details of what happens behind it.

$ aoox domain set --web panel.example.com --api api.panel.example.com \
  --acme-email you@example.com
Domain saved: panel.example.com (dashboard), api.panel.example.com (API).
The panel will restart for a few seconds to apply it — the connection to this API will drop briefly.

To undo it, aoox domain clear removes the domain and goes back to http://<server IP>:3000 (it asks first; --yes skips the prompt). The proxy and your applications' domains are not touched. See Removing the domain.

Updating aoox

Two different things get updated, with two commands. aoox update updates the CLI itself on your machine; aoox update panel updates the panel (the aoox-api/aoox-web images on the server).

The CLI: aoox update

Looks up the newest version on npm (no login, no panel needed). Every npm dist-tag is a candidate: a pre-release install is offered the newest version whatever its label (alpha, then beta, then rc), while a stable install only sees stable versions and never moves to a pre-release. Until a stable version exists, pre-releases are published under the latest tag, so a plain npm i -g @hideandseeklab/aoox installs the newest one. If the CLI was installed with npm it runs npm i -g @hideandseeklab/aoox@<version> for you; for the standalone tarball or a source checkout it prints the exact command to run instead of guessing.

$ aoox update --check
Update available: aoox CLI 0.1.0-rc.1 → 0.1.0-rc.2
Run: aoox update

$ aoox update
==> npm i -g @hideandseeklab/aoox@0.1.0-rc.2
Updated aoox CLI 0.1.0-rc.1 → 0.1.0-rc.2

$ aoox update
aoox CLI 0.1.0-rc.2 is up to date

If the npm registry cannot be reached the command fails with a clear message (non-zero exit status).

The panel: aoox update panel

Checks and applies an update for the panel itself (not the applications it deploys) — compares the aoox-api/aoox-web image digests on the registry, not just a version number.

$ aoox update panel
Running version: 0.1.0-rc.1
  api: hideandseeklab/aoox-api:latest (update available)
  web: hideandseeklab/aoox-web:latest (up to date)
Update available. Run with --apply to apply it.

$ aoox update panel --apply
Update applied — the panel will restart for a few seconds to apply it.

If the install is pinned to a version tag (API_IMAGE / WEB_IMAGE in .env.dist), a newer published version is shown but never applied by this command: it prints the latest version and how to move the pin (set both variables to the new tag, or remove them to follow latest, then run sudo aoox reinstall), and --apply refuses instead of reporting success.

Same as aoox domain set, needs INSTALL_DIR set. See Upgrading for the manual, over-SSH alternative.

Repairing an install (aoox reinstall)

aoox update panel only runs pull + up -d: it doesn't rewrite docker-compose.dist.yml and doesn't add new variables to .env.dist. An existing install therefore misses fixes that need a compose or env change (a real example: Terminal failing with TERMINAL_SSH_USER is not set after an update, because older installs never wrote that variable). aoox reinstall repairs that without touching your data. Run it on the panel server, as root:

$ sudo aoox reinstall --dry-run
$ sudo aoox reinstall

Safe to run repeatedly: when nothing needs changing, no file is rewritten (a backup folder is still made) and the containers are refreshed. If docker-compose.override.yml uses the !override tag (the option Only allow access through the domain) and the host's Docker Compose is older than 2.24.4, the command stops before changing anything: upgrade the Compose plugin or turn that option off in the dashboard first. Options: --dir (default /opt/aoox), --yes (no prompt), --no-pull, --terminal-ssh-user <user> (fills in or overrides that value), and --dry-run (print the plan only).

Without the CLI: edit .env.dist directly (e.g. add TERMINAL_SSH_USER=root) or use the Environment page in Settings, then docker compose … up -d.

Command reference

Configuration & environment variables

• Precedence: flag → environment → config.json contents. If none is complete, the CLI tells you to run aoox login.
• Working with several panels? Don't keep logging in and out — save one as the default and override it with --url/--token as needed.

In CI (no terminal)

aoox login needs an interactive terminal. In a pipeline, skip login and supply credentials via the environment:

deploy:
  image: node:20
  variables:
    AOOX_URL: https://panel.example.com
  script:
    - npx -p @hideandseeklab/aoox aoox whoami   # AOOX_TOKEN from a CI variable (masked)

Behind an antivirus or corporate proxy

Antivirus HTTPS scanning (AVG, Avast, Kaspersky, ESET, Bitdefender) and corporate proxies (Zscaler, Netskope, Fortinet, Palo Alto) re-sign HTTPS traffic with their own root certificate. It is installed in your operating system's certificate store, but Node only knows its own bundled list, so the CLI used to fail with a certificate error even though the panel's certificate is fine.

On Node 22.19+ or 24.5+ the CLI now trusts the system store in addition to Node's list, so it works without any setup. Certificate verification is never turned off. On older Node versions nothing changes and the error names the issuer it saw (for example AVG Web/Mail Shield Root).

• Opt out of the system store with AOOX_SYSTEM_CA=0.
• NODE_EXTRA_CA_CERTS=/path/to/root.pem still works if you would rather trust one specific root.
• Older Node: set NODE_OPTIONS=--use-system-ca (Node 22.15+ / 23.10+), upgrade Node, or add the panel's domain to the antivirus HTTPS-scanning exclusions.

Common pitfalls

Next steps