CLI reference

The nebula binary is the control plane. It also carries the commands that operate it and two that check files before you push them: nebula config validate and nebula template validate. This page is generated from the command tree of the release it describes.

Where to run itCopy Anchor Link

The binary is /usr/local/bin/nebula in the control plane image. When the installer sets up the host updater, which is the default, it also copies the binary to bin/nebula in the install directory (/opt/nebula/bin/nebula by default). The commands that read files, nebula config validate and nebula template validate, need no database and no running control plane.

SettingsCopy Anchor Link

Every flag of every command is also a setting. Set it three ways:

• the flag, such as --base-url;
• an environment variable named NEBULA_ plus the flag name in capitals with underscores, such as NEBULA_BASE_URL;
• a key of the same name as the flag in a nebula.yaml file, read from the working directory, from /etc/nebula, or from the path in --config.

A flag wins over the environment variable, and the environment variable wins over the file. The configuration reference groups the nebula serve settings by what they do.

Exit codesCopy Anchor Link

Global flagsCopy Anchor Link

Every command accepts these.

nebulaCopy Anchor Link

NebulaCtrl is a Kubernetes-native deployment control plane.

The control plane holds projects, environments, services and releases; an agent inside each cluster pulls desired state and reports what it observes.

nebula COMMAND

Commands:

• nebula changelog: Print this build's own release feed as JSON
• nebula config: Work with nebula.toml repository configuration files
• nebula migrate: Apply or inspect database migrations
• nebula openapi: Print the OpenAPI description to stdout
• nebula secrets: Maintain credentials sealed in the database
• nebula serve: Run the API, the user interface and the cluster agent link
• nebula template: Work with app template files
• nebula updater: Run the host service that performs console-requested control plane updates
• nebula version: Print the build version

nebula changelogCopy Anchor Link

Print this build's own release feed as JSON.

The same builder GET /api/v1/releases uses turns the embedded CHANGELOG.md into this output, so the two can never list different releases.

nebula changelog

nebula configCopy Anchor Link

Work with nebula.toml repository configuration files.

nebula config COMMAND

Commands:

• nebula config validate: Parse a nebula.toml file (a service's or a project's) and report every problem

nebula config validateCopy Anchor Link

Parse a nebula.toml file (a service's or a project's) and report every problem.

Reads FILE, or ./nebula.toml, and reports every problem in it, not only the first. A file with a top-level [services] or [databases] table is checked as a project config. Any other file is checked as a service's nebula.toml, once for each [environments.<name>] table it declares and for production, development and preview.

A problem prints as FILE:LINE: PATH: MESSAGE. A file with none prints FILE: ok and a summary of what it describes. The command exits 1 if it found a problem.

The check needs no database and no control plane, so it sees the file alone. What depends on the project, such as whether a referenced service exists, is checked by the control plane.

nebula config validate [FILE]

nebula config validate
nebula config validate services/api/nebula.toml

nebula migrateCopy Anchor Link

Apply or inspect database migrations.

nebula serve applies pending migrations at boot, so these commands exist for an operator who wants the schema moved without starting the server.

nebula migrate COMMAND

Commands:

• nebula migrate status: Show every migration and whether it has been applied
• nebula migrate up: Apply every pending migration

Flags:

nebula migrate statusCopy Anchor Link

Show every migration and whether it has been applied.

nebula migrate status

Also takes --database-url from its parent command.

nebula migrate upCopy Anchor Link

Apply every pending migration.

nebula migrate up

Also takes --database-url from its parent command.

nebula openapiCopy Anchor Link

Print the OpenAPI description to stdout.

The document is built from the same route table the server serves, so the generated TypeScript client cannot describe an API this binary does not have. It needs no database and binds no port.

nebula openapi [flags]

Flags:

nebula secretsCopy Anchor Link

Maintain credentials sealed in the database.

nebula secrets COMMAND

Commands:

• nebula secrets reseal: Re-encrypt every stored credential under the current master key

Flags:

nebula secrets resealCopy Anchor Link

Re-encrypt every stored credential under the current master key.

Re-encrypts every credential the database holds under the current master key (--master-key). Run it after rotating the master key, with the key you are retiring in --previous-master-keys so the old ciphertext can still be read.

It prints the current key id and how many rows it resealed in each table. Once it has finished, drop the previous keys from the configuration. It needs --database-url and --master-key.

nebula secrets reseal

Also takes --database-url, --master-key, --previous-master-keys from its parent command.

nebula serveCopy Anchor Link

Run the API, the user interface and the cluster agent link.

nebula serve [flags]

Flags:

nebula templateCopy Anchor Link

Work with app template files.

nebula template COMMAND

Commands:

• nebula template validate: Parse one or more template files and report every problem

nebula template validateCopy Anchor Link

Parse one or more template files and report every problem.

Parses each FILE as an app template and reports every problem in it. The file name, minus .yaml or .yml, must equal the template's slug.

A file with no problem prints FILE: ok and the template's name and service count. The command exits 1 if any file has a problem. It needs no database and no control plane.

nebula template validate FILE...

nebula template validate templates/redis-cache.yaml

nebula updaterCopy Anchor Link

Run the host service that performs console-requested control plane updates.

The updater runs on the control plane's host, not in its container. Every interval it polls the control plane over the host's loopback listener with the token in <dir>/.env (NEBULA_UPDATER_TOKEN). When an owner asked for an update it runs that version's install.sh from the get site, the command an operator would run by hand, verifies the new version, reinstalls the previous one if that fails, and reports the outcome. install.sh installs it as the nebula-updater systemd service.

nebula updater [flags]

Flags:

nebula versionCopy Anchor Link

Print the build version.

Prints the version, the Go version and the operating system and architecture the binary was built for.

nebula version