CLI reference

nebulactrl is a command line client for the control plane REST API. It authenticates with an API token; see API tokens and scopes and the API reference.

Global options#

Manage NebulaCtrl projects, services, deployments and servers through the control plane REST API.

A <service> is a service ID or project/env/slug. Configuration lives in ~/.config/nebulactrl/config.json (override with NEBULACTRL_CONFIG; NEBULACTRL_URL and NEBULACTRL_TOKEN override its fields).

Exit codes: 0 success, 1 failure, 2 wrong flags or arguments.

Command list#

nebulactrl backups#

Back up and restore managed databases.

nebulactrl backups

nebulactrl backups create#

Back up a database now.

nebulactrl backups create <database> --destination <name|id> [flags]

Options:

nebulactrl backups destinations#

Manage backup destinations (S3-compatible buckets, server directories).

nebulactrl backups destinations

nebulactrl backups destinations add#

Add a backup destination.

nebulactrl backups destinations add --name <n> --kind s3|local [flags]

The S3 secret key is never taken as an argument (it would show in process lists): pass --secret-key-file (- reads standard input) or set NEBULACTRL_BACKUP_SECRET_KEY.

Options:

nebulactrl backups destinations ls#

List backup destinations.

nebulactrl backups destinations ls

nebulactrl backups destinations rm#

Remove a backup destination.

nebulactrl backups destinations rm <name|id>

nebulactrl backups destinations test#

Write, read and delete a probe object through a server's agent.

nebulactrl backups destinations test <name|id> --server <server-id> [flags]

Options:

nebulactrl backups lock#

Keep a backup forever (never pruned or deleted).

nebulactrl backups lock <backup-id>

nebulactrl backups ls#

List a database's backups.

nebulactrl backups ls <database>

nebulactrl backups restore#

Restore a backup into a new database (default) or in place.

nebulactrl backups restore <backup-id> [flags]

By default the backup is restored into a NEW sibling database with fresh credentials; the original is untouched. With --in-place the database is overwritten after a safety backup; --confirm must equal its slug.

Options:

nebulactrl backups rm#

Delete a backup and its stored object.

nebulactrl backups rm <backup-id>

nebulactrl backups schedules#

Manage recurring backups.

nebulactrl backups schedules

nebulactrl backups schedules add#

Schedule recurring backups.

nebulactrl backups schedules add <database> --destination <name|id> --cron "0 3 * * *" [flags]

Options:

nebulactrl backups schedules ls#

List a database's backup schedules.

nebulactrl backups schedules ls <database>

nebulactrl backups schedules rm#

Remove a backup schedule.

nebulactrl backups schedules rm <schedule-id>

nebulactrl backups unlock#

Allow retention to prune a backup again.

nebulactrl backups unlock <backup-id>

nebulactrl build-settings#

Show or set the team's default build location and registry.

nebulactrl build-settings [--build-location target|build-server] [--registry <id|none>] [flags]

Without flags, prints the team default. With flags (administrators only), replaces it. Projects and services can override it. When no usable build server or registry exists a build falls back to the target server.

Options:

nebulactrl databases#

Manage managed databases.

nebulactrl databases

nebulactrl databases create#

Create a managed database (staged until deployed).

nebulactrl databases create --project <project> --env <env> --engine <engine> [--version <v>] [--name <name>] [--flavor postgis] [--database <db>] [--server <server>] [--accept-license] [flags]

Options:

nebulactrl databases engines#

List the database engines and versions.

nebulactrl databases engines

nebulactrl databases info#

Show a database's engine, exports and last reported state.

nebulactrl databases info <service>

nebulactrl databases promote#

Promote a read replica to primary (manual).

nebulactrl databases promote <replica> [--yes] [--accept-data-loss] [flags]

Prints the promotion plan. With --yes it promotes: a switchover while the old primary is reachable (it is frozen, stopped and fenced; no data is lost) or a forced promote otherwise (needs --accept-data-loss: what the replica had not received is lost). The old primary is fenced and never runs as a primary again. Variables that reference it are rewritten as staged changes. Manual: NebulaCtrl does not detect failures or switch automatically.

Options:

nebulactrl databases rebuild#

Rebuild a replica, or a fenced old primary as a replica of the new primary.

nebulactrl databases rebuild <replica-or-fenced-primary> [--follow <new-primary>] [flags]

Clones the primary again into a new data volume; the old volume is kept until it is deleted.

Options:

nebulactrl databases replicas#

Manage PostgreSQL read replicas.

nebulactrl databases replicas

nebulactrl databases replicas add#

Add a read replica of a PostgreSQL primary.

nebulactrl databases replicas add <primary> --server <server> [--name <name>] [--dry-run] [--accept-mesh-changes] [flags]

Creates a read replica service in the primary's environment and clones the primary into it. The replica runs on the primary's server or, with the server mesh enabled on both, on another server. Replication is asynchronous and manual: nothing is detected or switched automatically. --dry-run prints the plan only.

Options:

nebulactrl databases replicas ls#

List the read replicas of a database and their lag.

nebulactrl databases replicas ls <primary-or-replica>

nebulactrl databases replicas rm#

Remove a read replica.

nebulactrl databases replicas rm <replica> --yes [flags]

Deletes the replica's container and data volume, drops its slot, role and pg_hba.conf line on the primary and releases its mesh link.

Options:

nebulactrl databases restore#

Restore a database from a dump file on this machine.

nebulactrl databases restore <database> --file <dump> [--name <name>] [--server <server>] [--in-place --confirm <slug> [--destination <dest>]] [flags]

Uploads a dump file and restores it into a managed database: a pg_dump file (custom -Fc, tar -Ft or plain SQL, optionally .gz), a mysqldump / mariadb-dump SQL file (optionally .gz) or a mongodump --archive file. The format is detected from the file. The file is streamed through the control plane to the server's agent; nothing is stored on the way, and the default limit is 5 GiB.

By default the dump is restored into a NEW sibling database with fresh credentials (the original is untouched): point your apps at it when you are satisfied. With --in-place the database's data is replaced after a safety backup; --confirm must equal its slug, and --destination names the backup destination of the safety backup (default: the one of its schedule).

Examples:

nebulactrl databases restore shop/production/postgres --file shop.pgdump
  nebulactrl databases restore shop/production/postgres --file shop.sql.gz --in-place --confirm postgres --destination s3

Options:

nebulactrl databases reveal#

Print a connection string (audited as secret.reveal).

nebulactrl databases reveal <service> [--key DATABASE_URL] [flags]

Prints one derived connection variable in plain text to stdout. The action is recorded in the audit log and needs the deployments:write scope.

Options:

nebulactrl databases rotate#

Rotate the database password and stage its consumers.

nebulactrl databases rotate <service> [--dry-run] [flags]

Options:

nebulactrl databases upgrade#

Plan (default) or run a database version upgrade.

nebulactrl databases upgrade <service> <version> [--yes] [flags]

Prints the upgrade plan. With --yes it runs the upgrade: in-place engines stage the new image; PostgreSQL majors are converted with pg_upgrade into a new volume and then staged. Take a backup first.

Options:

nebulactrl deployments#

Inspect and roll back deployments.

nebulactrl deployments

nebulactrl deployments cancel#

Cancel a running deployment.

nebulactrl deployments cancel <deployment-id>

Cancels a deployment at whatever step it has reached. Before the agent started it the deployment ends as canceled at once. Once the agent runs it, the agent is asked to abort: a build is killed, the new containers are removed, routes are restored and a stopped previous release is started again, so the current release keeps serving. The deployment ends as canceled when the agent reports back (check with deployments status). Once the new release is live it is too late and the deployment finishes.

nebulactrl deployments download-logs#

Download a deployment's build and deploy log as a file.

nebulactrl deployments download-logs <deployment-id> [flags]

Writes the deployment's persisted lines (build, deploy and runtime streams; at most 10,000) in the order they were recorded, as plain text (<time> [<stream>] <line>) or NDJSON. Secret values are masked on the server. --streams all adds the agent's verbose debug trace.

Examples:

nebulactrl deployments download-logs 6f1c0d5e-… -o build.log

Options:

nebulactrl deployments ls#

List the deployments of a service.

nebulactrl deployments ls <service>

nebulactrl deployments rollback#

Redeploy the release of a previous deployment.

nebulactrl deployments rollback <deployment-id> [flags]

Creates a new deployment that points at the release of the given deployment. Application image and configuration only. Databases, volumes and external services are not rolled back.

Options:

nebulactrl deployments status#

Show a deployment and its step timeline.

nebulactrl deployments status <deployment-id>

nebulactrl domains#

Manage service domains.

nebulactrl domains

nebulactrl domains add#

Attach a hostname to a service.

nebulactrl domains add <service> <hostname> [flags]

Options:

nebulactrl domains generate#

Generate a domain from the server's base domain.

nebulactrl domains generate <service> [flags]

Options:

nebulactrl domains ls#

List a service's domains.

nebulactrl domains ls <service>

nebulactrl domains rm#

Remove a domain from a service.

nebulactrl domains rm <service> <hostname|domain-id>

nebulactrl domains www#

Turn the www/apex redirect of a domain on or off.

nebulactrl domains www <service> <hostname|domain-id> <on|off>

on routes the www/apex counterpart of the domain (www.<host>, or the host without its www.) and answers it with a 301 redirect to the domain, keeping the path and query. Both hostnames get certificates and each needs its own DNS record. off removes the redirect. The change is staged until the next deploy. Needs proxy:write; the domain must be a whole-host serve domain without a path prefix.

Examples:

nebulactrl domains www acme/production/web example.com on

nebulactrl envs#

Manage environments.

nebulactrl envs

nebulactrl envs clone#

Clone an environment into a new, non-production one.

nebulactrl envs clone <env> --project <project> --name <name> [--domains drop|suffix] [--dry-run] [flags]

Create a new environment with a staged copy of every service of <env>: configuration, variables, the environment's shared variables, volume definitions, links and the canvas layout. Slugs are kept, so ${{postgres.DATABASE_URL}} in a cloned service points at the cloned postgres. Secrets are copied sealed and generated values are generated again. Databases are new and empty (restore a dump into them); volumes are new and empty. Nothing runs until the services are deployed.

Options:

nebulactrl envs ls#

List the environments of a project.

nebulactrl envs ls --project <project> [flags]

Options:

nebulactrl import#

Import a project from another tool.

nebulactrl import

nebulactrl import compose#

Import a Docker Compose project as staged services.

nebulactrl import compose <docker-compose.yml|-> --project <p> --env <e> --server <s> [flags]

Reads a Compose file (a local file, stdin with -, or a file in a git repository with --repo) and stages one NebulaCtrl service per Compose service in the environment, grouped on the canvas and linked in deploy order. Nothing is deployed unless you pass --deploy.

Files next to the Compose file (.env, env_file entries, bind-mounted config files) are read from disk. Host names of other services in variables are rewritten to references, and official database images become managed databases unless you turn that off. Use --plan to review without changing anything. Per-service decisions are written as <service>=<value> or <service>.<KEY>.

With --as-stack the whole file becomes ONE service (a native Compose stack): the file is kept as written, the .env entries become the stack's variables (used for ${VAR} interpolation only), and domains are suggested per component. A stack runs under the safe allow-list (no privileged mode, host network, devices, Docker socket or host bind mounts, no build:) unless an instance admin made the server unrestricted; violations are listed and block the import. In stack mode --secret, --not-secret and --skip-var take the variable name (<KEY>); --domain and --port take the component name.

Options:

nebulactrl import coolify#

Import projects, applications and databases from a Coolify v4 instance as staged services.

nebulactrl import coolify --url <coolify url> --server <server> [flags]

Reads a Coolify instance through its API and stages the same projects and environments here: applications become image or git services (Dockerfile builds stay Dockerfile builds, Nixpacks becomes Railpack), databases become managed databases of the same engine and version, domains, health checks, resource limits, custom Docker options, deployment commands and variables come along. Variables that point at a Coolify database or application are rewritten to ${{service.EXPORT}} references; credentials, locked values and secret-looking keys are stored as secrets. Nothing is deployed unless you pass --deploy, and database and volume DATA is never copied (the plan prints the follow-up commands).

The Coolify API token needs the read and read:sensitive abilities (Keys & Tokens → API tokens in Coolify); read:sensitive is what returns variable values and custom Docker options. The token is read from --token-env (default COOLIFY_TOKEN), --token-file or --token, sent to your NebulaCtrl server for this one request, and never stored or printed. Registry pull credentials cannot be read from Coolify: give them with --registry-user and --registry-token-env.

Use --plan (or --dry-run) to review without changing anything: it lists every resource, its variables by key (never values), the rewritten references and everything that is not imported. Per-resource decisions name the resource by its Coolify name or UUID, variables as <resource>.<KEY>.

Options:

nebulactrl instance#

Settings of the whole installation (instance admin only).

nebulactrl instance

nebulactrl instance dashboard-access#

Who may reach the dashboard and how its certificate is issued.

nebulactrl instance dashboard-access

nebulactrl instance dashboard-access get#

Show the dashboard's allow list and certificate method.

nebulactrl instance dashboard-access get

nebulactrl instance dashboard-access set#

Change the dashboard's allow list and certificate method.

nebulactrl instance dashboard-access set [--allow <cidr>]... [--tailnet-only | --clear-allow] [--dns-resolver <provider> | --http-01] [--confirm-lockout] [flags]

Restricts who may reach the dashboard's hostname (an IP allow list on its route) and chooses how its certificate is issued. Settings you do not name stay as they are. --allow replaces the list (repeat it or separate CIDRs with commas; IPv4 and IPv6). --tailnet-only is the list 100.64.0.0/10, fd7a:115c:a1e0::/48. Agents on other servers and webhooks reach the control plane through the same hostname, so keep their addresses in the list. The change is refused (409 dashboard_lockout) when the list leaves out the address you are connecting from, unless --confirm-lockout is set. --dns-resolver needs a resolver of that provider on the control-plane server (Servers, Proxy). Run from the host with an SSH tunnel to recover from a lock-out.

Options:

nebulactrl login#

Store the control plane URL and API token.

nebulactrl login --url <url> --token <token> [flags]

Verifies the token against GET /me and writes ~/.config/nebulactrl/config.json (mode 0600). Pass --token - to read the token from stdin; NEBULACTRL_TOKEN is used when --token is omitted.

Options:

nebulactrl members#

Manage the members of your team.

nebulactrl members

nebulactrl members invite#

Invite someone by email, or create a link invite.

nebulactrl members invite [--email <address>] --role <role> [flags]

Options:

nebulactrl members ls#

List the members of the token's team.

nebulactrl members ls

nebulactrl mesh#

Manage the server mesh (a tailnet of your servers).

nebulactrl mesh

nebulactrl mesh check#

Test whether the server's mesh node reaches the other servers.

nebulactrl mesh check <server>

nebulactrl mesh disable#

Remove a server from the mesh.

nebulactrl mesh disable <server>

nebulactrl mesh enable#

Join a server to the mesh (adds one tagged tailnet device).

nebulactrl mesh enable <server> [flags]

Options:

nebulactrl mesh links#

Show the cross-server links of an environment: links, grants and routes.

nebulactrl mesh links <project/env>

nebulactrl mesh reconcile#

Create (add) or clean up (repair) the cross-server links of an environment now.

nebulactrl mesh reconcile <project/env> [flags]

Mode add creates every link the environment's variable references and canvas links need. It adds tailnet devices (tagged devices may be billed by Tailscale), so it needs --accept-mesh-changes. Mode repair only removes grants whose source is gone; it never adds a device.

Options:

nebulactrl mesh reprovision#

Re-create the server's mesh node (new device and tailnet IP).

nebulactrl mesh reprovision <server>

nebulactrl mesh service#

Show what a service exposes on the mesh, which providers it reaches and who reaches it.

nebulactrl mesh service <service>

nebulactrl mesh status#

Show the mesh: nodes, links and the ACL state.

nebulactrl mesh status

nebulactrl projects#

Manage projects.

nebulactrl projects

nebulactrl projects create#

Create a project (with a production environment).

nebulactrl projects create <name> [flags]

Options:

nebulactrl projects ls#

List projects.

nebulactrl projects ls

nebulactrl projects update#

Rename a project or set where its services are built.

nebulactrl projects update <project> [--name <n>] [--description <d>] [--build-location inherit|target|build-server [--build-server <server>] [--registry <id>]] [flags]

--build-location overrides the team default for every git service of the project (a service can override it again). The placement is replaced as a unit: --build-server pins a build server and --registry names the registry; an omitted one is cleared (the control plane picks a build server, the team default registry applies).

Options:

nebulactrl servers#

Manage Docker hosts.

nebulactrl servers

nebulactrl servers enroll-token#

Create a one-time agent enrollment token.

nebulactrl servers enroll-token --name <name> [flags]

Registers a pending server and prints the one-hour, single-use enrollment token together with the command that installs the agent on the host. The token is shown once.

Options:

nebulactrl servers ls#

List servers.

nebulactrl servers ls

nebulactrl servers revoke#

Revoke a server's agent identity.

nebulactrl servers revoke <server-id|name>

Disconnects the agent and cancels its pending commands. The agent must re-enroll to come back.

nebulactrl servers unrestricted#

Show, enable or disable the Unrestricted switch of a server (instance admin).

nebulactrl servers unrestricted <server-id|name> [--on --confirm <name> | --off] [flags]

By default Compose stacks and services run under safe allow-lists. An unrestricted server lifts them for everything on it: privileged mode, host networking, devices, GPUs, a custom runtime, the host PID namespace, unconfined seccomp or AppArmor, NET_ADMIN, SYS_ADMIN, the Docker socket and host bind mounts. Anyone who can deploy there can take over the server, so only the instance admin can switch it, and enabling needs --confirm with the server's exact name. Disabling does not stop running containers; the next deploy of something that needs it fails. Without --on or --off, prints the current state.

Options:

nebulactrl servers update#

Set a server's role and build settings.

nebulactrl servers update <server-id|name> [--role deployments|builds|both] [--max-builds <n>] [--allow-emulation[=false]] [--allow-previews[=false]] [flags]

Roles: deployments runs services (the default), builds only builds images for other servers and pushes them to a registry, both does both. A build server needs an agent that can build and push (build.push). --max-builds caps parallel builds (1-16, default 2; more queue). --allow-emulation lets it build for another CPU architecture (slow). --allow-previews lets pull request previews build on it (off: previews build on their own server).

Options:

nebulactrl services#

Manage services.

nebulactrl services

nebulactrl services build-plan#

Preview how a git service would be built.

nebulactrl services build-plan <service>

Asks the service's server to clone the branch head and report the build method (Dockerfile, Railpack or a starter Dockerfile), the detected providers and the start command. Nothing is built or deployed.

nebulactrl services clone#

Clone a service (staged copy; secrets are copied sealed).

nebulactrl services clone <service> [--env <env> [--project <project>]] [--name <name>] [--domains drop|suffix] [--dry-run] [flags]

Clone a service into the same or another environment. The clone is staged: nothing runs until it is deployed.

It gets the configuration, variables (secrets stay secret, generated values are generated again), volume definitions (new, empty volumes) and, in the same environment, the source's links. A managed database is created new and empty: restore a dump into it. Domains are dropped by default or cloned with a suffix.

Options:

nebulactrl services create#

Create a service (staged until deployed).

nebulactrl services create --project <project> --env <env> --name <name> (--image <ref> | --git <url> [--branch <b>]) [--server <server>] [--port <n>] [flags]

Options:

nebulactrl services deploy#

Deploy a service.

nebulactrl services deploy <service> [flags]

Starts a deployment and returns once it is accepted (HTTP 202). With --wait, polls until the deployment reaches a terminal status and exits 0 only when it is succeeded. With --no-cache a git service builds this one deployment without any cache (docker build --no-cache --pull, no reuse of an image a build server already pushed); later deployments build normally.

Options:

nebulactrl services deploy-hook#

Show, enable, disable or rotate a service's deploy hook.

nebulactrl services deploy-hook <service> [--enable|--disable|--rotate] [flags]

A deploy hook is a URL (POST /hooks/deploy/<service-id>/<secret>) that deploys the service like a manual deploy, for CI pipelines and container registries (Docker Hub, GHCR). Without a flag the command shows the hook's state.

--enable creates a secret and prints the URL; --rotate replaces the secret of an enabled hook and prints the new URL; --disable turns the hook off and deletes the secret. The URL is shown once and cannot be read again. Managing a hook needs the deployments:write scope.

Options:

nebulactrl services docker#

Show or set a service's Docker options (staged until the next deployment).

nebulactrl services docker <service> [flags]

Without flags, prints the service's Docker options. With flags, changes them and stages the service. The options are typed: there is no free-text docker run string. Hardening options (--cap-drop ALL, --no-new-privileges, --read-only, --pids-limit), --hostname, --dns, curated --sysctl, --user and --group-add work on every server.

--device, --gpus, --runtime, --privileged, --pid-host, --seccomp-unconfined, --apparmor-unconfined (and the NET_ADMIN and SYS_ADMIN capabilities, set in the web UI) work only on a server an instance admin made unrestricted (nebulactrl servers unrestricted): they can hand over the host. Other servers answer 422 requires_unrestricted_server. Capabilities to add, ulimits, shm size, extra hosts, labels, tmpfs and the entrypoint are edited in the web UI.

Options:

nebulactrl services download-logs#

Download a service's stored runtime logs as a file.

nebulactrl services download-logs <service> [flags]

Writes the service's stored runtime log (the server keeps 7 days by default), oldest first, as plain text (<time> <line>) or NDJSON. Secret values are masked on the server. At most 200,000 lines: a longer range ends with a note, so narrow it with --from/--to. Needs the logs:read scope and the service's server online.

Examples:

nebulactrl services download-logs acme/production/web --from 24h -o web.log
  nebulactrl services download-logs web --format ndjson --grep 'level:error' > errors.ndjson

Options:

nebulactrl services logs#

Show runtime logs of a service.

nebulactrl services logs <service> [flags]

Options:

nebulactrl services ls#

List the services of an environment.

nebulactrl services ls --project <project> --env <env> [flags]

Options:

nebulactrl services maintenance#

Put a service into maintenance mode, or take it out.

nebulactrl services maintenance <service> on|off [--title <t>] [--message <m>] [--eta <rfc3339|duration>] [flags]

While on, every domain of the service answers HTTP 503 with a maintenance page and a Retry-After header instead of reaching the service. It takes effect immediately without a deployment, and it is never staged or rolled back. --eta takes an RFC 3339 time (2026-11-02T09:30:00Z) or a duration from now (45m, 2h). The page text and ETA are only used with on; off keeps the stored text for next time.

Options:

nebulactrl services move#

Move a service to another environment (staged until the next deploy).

nebulactrl services move <service> --env <env> [--project <project>] [--force] [--dry-run] [flags]

Move a service to another environment. It keeps running where it is until its next deployment, which joins the new environment's network and variables. References are checked first: variables that point at services staying behind, and other services' variables that point at the moved one, break. Without --force a move that breaks references is refused; --dry-run prints the plan. Canvas links of the service are removed.

Options:

nebulactrl services restart#

Restart a service's container.

nebulactrl services restart <service>

nebulactrl services run#

Run a one-off command in a container of the service's image.

nebulactrl services run <service> -- <command...> [flags]

Runs the command (argv, no shell; use -- sh -c '...' for shell syntax) in a throwaway container of the service's current image, with its environment, networks and resource limits, on its server. Prints the output and exits with the command's exit code. Needs the deployments:write scope and is audited.

Options:

nebulactrl services scale#

Set the number of replicas or turn on autoscaling.

nebulactrl services scale <service> [<replicas>] [--autoscale min:max[:target]|off] [flags]

Runs a stateless service (no volumes, an HTTP port) on 1-10 replicas on its server. The change applies immediately without a deployment and without a rebuild. --autoscale min:max[:target] scales on CPU (target percent of the replica's CPU limit, default 70); --autoscale off returns to manual scaling.

Options:

nebulactrl services shell#

Open an interactive shell in a service's container.

nebulactrl services shell <service> [-- command args…] [flags]

Opens a terminal in a running replica of the service (bash if the image has it, else sh), or runs the command after -- with a terminal attached. Needs the Owner, Admin or Developer role and a token with deployments:write. Production services need --production. Sessions are audited (never their input or output) and close after 15 minutes without input.

Examples:

nebulactrl services shell acme/production/web
  nebulactrl services shell web --replica 1 -- psql -U postgres

Options:

nebulactrl services update#

Set where and how a service is built.

nebulactrl services update <service> [--build-location inherit|target|build-server] [--build-server <server|none>] [--registry <id|none>] [--submodules auto|on|off] [flags]

The service's own override of the project and team build settings; inherit follows them. none clears a pin or registry. --submodules sets the git submodule checkout (auto: recursive when the repository has a .gitmodules file; on: always, a failure fails the build; off). The change is staged until the next deployment, like every setting. Compose stacks are edited in the web UI.

Options:

nebulactrl tasks#

Cron tasks and their runs.

nebulactrl tasks

nebulactrl tasks create#

Schedule a recurring command.

nebulactrl tasks create <service> --name <name> --schedule <cron> -- <command...> [flags]

Runs the command (argv, no shell; use -- sh -c '...' for shell syntax) in a throwaway container of the service's current image with its environment. The schedule is a 5-field cron expression or @hourly/@daily/@weekly/@monthly, evaluated in --timezone (an IANA name such as Europe/Berlin; default UTC). Daylight-saving changes keep the wall-clock time: a run in the skipped hour is skipped for that day, a repeated hour runs once.

Options:

nebulactrl tasks logs#

Print the output of a run (follows a run that is still active).

nebulactrl tasks logs <run-id>

nebulactrl tasks ls#

List a service's cron tasks.

nebulactrl tasks ls <service>

nebulactrl tasks rm#

Delete a cron task and its run history.

nebulactrl tasks rm <service> <task>

nebulactrl tasks run#

Run a cron task now and follow its output.

nebulactrl tasks run <service> <task> [flags]

Starts a run immediately (whatever the schedule), prints its output and exits with the command's exit code.

Options:

nebulactrl tasks runs#

Run history of a service's tasks and one-off commands.

nebulactrl tasks runs <service> [flags]

Options:

nebulactrl tasks update#

Change a cron task's schedule or time zone.

nebulactrl tasks update <service> <task> [--schedule <cron>] [--timezone <zone>] [flags]

Changing the schedule or the time zone recomputes the next run from now; the new next run is printed. The time zone is an IANA name such as Europe/Berlin (UTC when never set).

Examples:

nebulactrl tasks update acme/production/web nightly --timezone Europe/Berlin

Options:

nebulactrl teams#

Manage teams.

nebulactrl teams

nebulactrl teams create#

Create a team (you become its owner; needs an admin-scope token).

nebulactrl teams create <name>

nebulactrl teams ls#

List your teams and the saved token per team.

nebulactrl teams ls

nebulactrl teams switch#

Use the saved token of another team.

nebulactrl teams switch <slug>

nebulactrl templates#

Browse and install one-click templates.

nebulactrl templates

nebulactrl templates install#

Install a template as staged services (or deploy right away).

nebulactrl templates install <template> --project <p> --env <e> --server <s> [--input KEY=VALUE]... [--deploy] [flags]

Options:

nebulactrl templates installed#

List the template stacks of an environment.

nebulactrl templates installed --project <p> --env <e> [flags]

Options:

nebulactrl templates ls#

List catalog templates.

nebulactrl templates ls [--category c] [--license class] [--search text] [flags]

Options:

nebulactrl templates plan#

Preflight an install (changes nothing).

nebulactrl templates plan <template> --project <p> --env <e> [--server <s>] [--input KEY=VALUE]... [flags]

Options:

nebulactrl templates rm#

Delete a template stack.

nebulactrl templates rm <instance-id> --confirm <template-id> [--delete-volumes] [flags]

Options:

nebulactrl templates show#

Show a template: services, inputs and licence.

nebulactrl templates show <template>

nebulactrl templates update#

Show what a newer template revision changes, or stage it (--apply).

nebulactrl templates update <instance-id> [--apply] [--input KEY=VALUE]... [flags]

Without --apply this prints the diff between the template as installed and the catalog's current revision and changes nothing. With --apply the changes marked 'apply' are staged as ordinary edits (nothing is deployed). Fields you changed are kept; databases, routes and services are never touched.

Options:

nebulactrl vars#

Manage service environment variables.

nebulactrl vars

nebulactrl vars history#

Show a variable's versions (secrets show a fingerprint only).

nebulactrl vars history <service> KEY

nebulactrl vars ls#

List variables (secret values are never shown).

nebulactrl vars ls <service> [flags]

Options:

nebulactrl vars rm#

Delete variables (staged until the next deploy).

nebulactrl vars rm <service> KEY...

nebulactrl vars rotate#

Replace a generated variable's value (staged, never deployed).

nebulactrl vars rotate <service> KEY [--dry-run] [flags]

Re-runs the generators of a variable created with ${{secret(..)}} and similar. --dry-run prints the plan only: which services consume the value, in which order to deploy them, and any blockers. Without it the new value is staged on this service and on every consumer; nothing is deployed. Database credentials cannot be rotated this way once deployed.

Options:

nebulactrl vars set#

Set variables (staged until the next deploy).

nebulactrl vars set <service> KEY=VALUE... [--secret] [--scope build] [flags]

Upserts variables on a service. Changes are staged: run services deploy to apply them. Values are never echoed. Use KEY=- to read a value from stdin, which keeps secrets out of the shell history and process list. A variable that is already secret stays secret.

A value may contain generators that run once, on the server: KEY='${{secret(32)}}' stores a random secret. Running the same command again keeps the generated value (use vars rotate to replace it). Other forms: ${{service-slug.KEY}}, ${{KEY}}, ${{shared.KEY}}; write $${{ for a literal ${{. --scope build passes the variable to image builds of git services (--build-arg, or a BuildKit secret when it is secret); --scope both also keeps it in the container.

Options:

nebulactrl vars shared#

Manage shared variables of the team (@team), a project (<project>) or an environment (<project>/<env>).

nebulactrl vars shared

nebulactrl vars shared ls#

List shared variables.

nebulactrl vars shared ls <@team|project[/env]>

nebulactrl vars shared rm#

Delete shared variables.

nebulactrl vars shared rm <@team|project[/env]> KEY...

nebulactrl vars shared rotate#

Replace a generated shared variable (staged, never deployed).

nebulactrl vars shared rotate <@team|project[/env]> KEY [--dry-run] [flags]

Options:

nebulactrl vars shared set#

Set shared variables (restages the services that use them).

nebulactrl vars shared set <@team|project[/env]> KEY=VALUE... [--secret] [flags]

Options:

nebulactrl vars shared share#

Stage KEY=${{shared.KEY}} on services.

nebulactrl vars shared share <@team|project[/env]> KEY <service>...

A shared variable reaches a service only through an explicit reference row. This stages KEY=${{shared.KEY}} on each service (services given as ID or project/env/slug).