uncloud/website/docs/7-cli-config-reference.md

CLI configuration file

The uc CLI stores cluster connection details in a YAML configuration file. Every time you run a command like uc ls or uc deploy, it reads this file to figure out which cluster to connect to and how to reach its machines over SSH.

You rarely need to edit this file by hand. uc creates and updates it automatically when you run commands like uc machine init, uc machine add, or uc ctx.

Config location

The default config file path is ~/.config/uncloud/config.yaml. You can change this with the --uncloud-config global flag or the UNCLOUD_CONFIG environment variable:

# Use a custom config file for this command
uc --uncloud-config ./my-config.yaml ls

# Or set the environment variable to use a custom config file for all commands
export UNCLOUD_CONFIG=~/my-uncloud-config.yaml
uc ls

Config structure

Here is an example config file for a setup with two clusters, prod and dev:

current_context: prod
contexts:
  prod:
    connections:
      - ssh: user@137.123.45.67
      - ssh: myserver  # host alias from SSH config
  dev:
    connections:
      - ssh: ubuntu@dev.example.com
        ssh_key_file: ~/.ssh/id_ed25519
        machine_id: 3f60c88ac6b0f250d8aecb92a090922f

The config has two top-level attributes: current_context and contexts.

current_context

The name of the active context. uc uses this context by default when you run any command. You can switch to a different context with an interactive uc ctx command, non-interactively with uc ctx use, or the --context flag.

contexts

A map of named contexts. Each context represents a cluster and contains a list of machine connections.

A context is not the same thing as a cluster. It is your local view of a cluster: which machines you can connect through and in what order to try them. Two people on the same team can have different contexts pointing to the same cluster, each with their own preferred entry point.

You can also create multiple contexts for the same cluster. For example, one that connects through a machine with a public IP when you're not in the office, and another that connects through a private machine on the office network when you're on-site to reduce latency.

connections

Each connection in the list represents a machine in the cluster. uc only needs to reach one machine to work with the entire cluster. That machine acts as an entry point and forwards requests to other machines as needed.

The first connection in the list is the default one that uc tries first. If it's unavailable, uc moves on to the next one. You can change the default connection with an interactive command uc ctx conn.

Every connection must have exactly one connection type attribute:

Attribute	Format	Description
ssh	user@host[:port]	Connect using the system ssh command with full SSH config support (default for new connections added with uc machine init/add)
ssh_go	user@host[:port]	Connect using the Go's built-in SSH library (no SSH config support)
tcp	host:port	Connect directly to the machine gRPC API over TCP (for advanced users with custom setups)
unix	/run/uncloud/uncloud.sock	Connect directly to the machine gRPC API over a Unix socket (for running uc locally on the cluster machines)

A connection can also have these optional attributes:

Attribute	Description
ssh_key_file	Path to the SSH private key for this machine (maps to -i in the ssh command)
machine_id	Unique identifier of the machine (used to match and remove the connection when removing a machine with uc machine rm)

How the config gets created

You don't need to create this file yourself. uc manages it for you:

1. uc machine init creates a new context and adds the first machine connection. If you don't specify a context name with -c, it uses default. If default already exists, it auto-increments to default-1, default-2, and so on.
2. uc machine add appends a new machine connection to the current context.

For example, after initialising a cluster:

uc machine init root@203.0.113.1 -c prod

uc creates a config file that looks like this:

current_context: prod
contexts:
  prod:
    connections:
      - ssh: root@203.0.113.1
        ssh_key_file: ~/.ssh/id_ed25519
        machine_id: a1b2c3d4e5f6

Connection resolution

When you run a command, uc determines which cluster to connect to using this priority:

1. If --connect is set, uc connects directly to that machine and ignores the config file entirely.
2. If --context is set, uc uses that context from the config.
3. Otherwise, uc uses current_context from the config.

Once the context is resolved, uc tries each connection in the context's list in order until one succeeds.

Global flags and environment variables

These flags are available on every uc command. Each flag can also be set with an environment variable. The flag takes priority if both are set.

Flag	Environment variable	Description
--uncloud-config	UNCLOUD_CONFIG	Path to the config file
--context	UNCLOUD_CONTEXT	Use a specific context instead of the current one
--connect	UNCLOUD_CONNECT	Bypass the config file and connect directly

The --connect flag

The --connect flag lets you run one-off commands against a machine without setting up a config file. It accepts these formats:

# System 'ssh' command (default)
uc --connect root@203.0.113.1 ls

# System 'ssh' command (explicit scheme)
uc --connect ssh://root@203.0.113.1 ls

# Go's built-in SSH (no SSH config support)
uc --connect ssh+go://root@203.0.113.1 ls

# Direct TCP
uc --connect tcp://10.210.0.1:1234 ls

# Unix socket
uc --connect unix:///run/uncloud/uncloud.sock ls

:::warning

You can't use --connect with uc machine init. The init command needs the config file to save the new cluster context.

:::

Managing contexts

Use these commands to work with contexts in your config:

• uc ctx: Switch contexts using an interactive TUI
• uc ctx ls: List all contexts and see which one is current
• uc ctx use: Switch the current context
• uc ctx conn: Change the default connection for the current context

You can also set x-context in your Compose file to pin a specific context for deployments. See Deploy to a specific cluster context for details.