Node

up node

Manage nodes

Synopsis

Register, provision, and operate the nodes that up builds on and deploys to.

Use node add to provision a remote host over SSH and register it with the control node. node init bootstraps a node on the current machine (generating its auth token), and node start runs the node agent. node enable/node disable install the agent as a system service.

Run up node with no subcommand to list registered nodes.

up node [flags]

Options inherited from parent commands

  -o, --output string   output format: table, json, yaml (list commands only) (default "table")
  -q, --quiet           suppress output
  -v, --verbose count   enable debug output (-v debug, -vv trace)

up node add

Provision and register a remote node (ssh://user@host[:port])

Synopsis

Connect to a remote host over SSH, install the up binary and a service manager unit, and register the node with the control node. The node is given a display name (defaults to the SSH hostname). Roles default to build and deploy; pass –roles to choose them explicitly.

Use –identity-file to specify the SSH private key and –service-manager to pick systemd or openrc (auto-detected by default).

up node add <ssh-url> [flags]

Examples

  # Provision and register a remote node
  up node add ssh://root@203.0.113.10 -i ~/.ssh/id_ed25519 --name edge-1

  # Provision with an explicit service manager
  up node add ssh://deploy@db.example.com --service-manager systemd

Options

  -i, --identity-file string     path to SSH private key
      --name string              display name for the node (defaults to SSH hostname)
      --roles strings            roles for the node (default build,deploy)
      --service-manager string   service manager on remote (auto|systemd|openrc) (default "auto")

up node config

View or change the local node configuration

Synopsis

Show the effective configuration up uses for a node, or change one stored value. With no –node the local node is read from disk, which is safe before up node init. With –node the value is read or changed on that remote node through the control node.

Reading never writes anything: values the file does not set fall back to their defaults, and each value notes whether it comes from the file, from an environment variable, or from a default. node_token is masked unless –show-token is passed.

The values are stored in /config.toml, whose path the output shows as config_path. UP_NODE_URL and UP_NODE_TOKEN override node_url and node_token at runtime, so when either is set a saved value does not take effect. node_token and db_path can only be set locally.

up node config [flags]

Examples

  # Show the effective configuration
  up node config

  # Show it as JSON with the token revealed
  up node config -o json --show-token

  # Read a remote node's configuration
  up node config --node edge-1

  # Change one value
  up node config set node_url https://control.example.com

  # Change a remote node's roles through the control node
  up node config set roles build,deploy --node edge-1

Options

  -n, --node string   target a remote node by name (default: the local node)
      --show-token    reveal node_token instead of masking it

up node config set

Change one local node configuration value

Synopsis

Set one key in the local node config file. Other keys, including ones up does not know about, are preserved, and defaults are never written back: only the changed key is stored, so this works before up node init.

Keys: node_url, node_token, roles, db_path, log_retention_lines.

Omit the key to pick one interactively, or omit the value to be prompted for it (masked for node_token, a multi-select for roles). In a non-interactive shell both the key and the value must be given.

up node config set [key] [value] [flags]

Examples

  # Point the CLI at a remote control node
  up node config set node_url https://control.example.com
  up node config set node_token

  # Choose the roles this node runs
  up node config set roles build,deploy

up node disable

Stop and disable the up node system service

Synopsis

Stop the up node system service and uninstall it (systemd or openrc). The binary and node state are left in place; use up node enable to reinstall.

up node disable [flags]

Options

      --service-manager string   service manager: auto, systemd, openrc (default "auto")

up node enable

Install and start up node as a system service

Synopsis

Install the up node agent as a system service (systemd or openrc), enable it to start on boot, and start it now. Use –service-manager to override auto-detection.

up node enable [flags]

Examples

  # Install and start the node service with systemd
  up node enable --service-manager systemd

Options

      --service-manager string   service manager: auto, systemd, openrc (default "auto")

up node init

Bootstrap the node (idempotent)

Synopsis

Prepare the current machine to run as a node: generate the auth token if missing and set up local state. Safe to run more than once.

up node init [flags]

up node list

List registered nodes

Synopsis

List the nodes known to the control node as a table, including their roles and status. This is the default action when up node is run with no subcommand.

up node list [flags]

up node prune

Remove unused images from nodes

Synopsis

Remove local images that up no longer needs from one node, or from every registered node when –node is omitted. Only images that belong to a configured registry are considered, images a container uses are kept, and images an active or in-flight deployment may still need are kept.

Without –force the command only lists what it would remove.

up node prune [flags]

Examples

  # Show what would be removed from every node
  up node prune

  # Show what would be removed from one node
  up node prune --node edge-1

  # Remove them
  up node prune --node edge-1 --force

Options

      --force         remove the images; without it, only list what would be removed
  -n, --node string   prune only this node (default: every node)

up node remove

Stop the agent on a remote node and deregister it

Synopsis

Deprovision a node: stop its agent, remove the service manager unit on the remote host, and deregister it from the control node. A node that still runs services cannot be removed without –force, which forces removal of the dependents.

Pass the node ID as an argument or omit it to pick from a list.

up node remove [node-id] [flags]

Examples

  # Remove a node, confirming dependents
  up node remove node-abc123 --force

Options

      --force                  skip the removal confirmation
  -i, --identity-file string   path to SSH private key (overrides stored key)

up node start

Run the node HTTP API

Synopsis

Start the node agent: it serves the node HTTP API, runs builds and deployments according to its configured roles, and connects to the control node. Use –roles to enable a subset of roles (control, build, deploy); otherwise the configured or default roles are used.

up node start [flags]

Examples

  # Start with only build and deploy roles
  up node start --roles build,deploy

Options

      --roles strings   comma-separated roles to enable (control,build,deploy); defaults to config or all