NICo Admin CLI

nico-admin-cli is the command-line tool for managing a NICo site. It communicates with nico-api over gRPC with mutual TLS (mTLS).

Building

From the repository root:

# Debug build (faster compile, larger binary)
cargo build -p nico-admin-cli
# Release build (optimized, for deployment)
cargo build -p nico-admin-cli --release

The binary is written to:

• target/debug/nico-admin-cli (debug)
• target/release/nico-admin-cli (release)

Connecting to nico-api

The CLI needs three things to connect:

1. API URL — where nico-api is listening
2. Root CA certificate — to verify the server’s TLS certificate
3. Client certificate + key — to authenticate this client to the server

TLS options

Settings prefer CLI flags, then environment variables, then config-file keys, then defaults or file-location fallbacks. The client certificate and key resolve independently. When both values are present, the CLI uses that pair, even when one comes from a CLI flag and the other from an environment variable. When either is absent, it uses the complete config-file pair, then the client-cert fallbacks.

Config file

Instead of passing flags every time, create $HOME/.config/nico_api_cli.json:

{
  "api_url": "https://nico-api.example.com:1079",
  "root_ca_path": "/etc/nico/certs/ca.crt",
  "client_cert_path": "/etc/nico/certs/client.crt",
  "client_key_path": "/etc/nico/certs/client.key",
  "rms_root_ca_path": "/etc/nico/certs/rms-ca.crt"
}

Example invocations

# Explicit flags
nico-admin-cli \
  --api-url https://nico-api.example.com:1079 \
  --root-ca-path /etc/nico/certs/ca.crt \
  --client-cert-path /etc/nico/certs/client.crt \
  --client-key-path /etc/nico/certs/client.key \
  version
# With config file (no flags needed)
nico-admin-cli version

SOCKS5 proxy

The CLI honors http_proxy / https_proxy (or their uppercase variants) only when the URL scheme is socks5. HTTP/HTTPS proxies are rejected with a “Only SOCKS5 Proxy supported” error. This is enforced in get_proxy_info(); see crates/tls/src/client_config.rs.

export https_proxy=socks5://localhost:1080
nico-admin-cli machine show

Client-cert fallbacks

If neither flag, env var, nor config file supplies the client cert/key, the CLI tries these in order before giving up. Each step requires both the cert and the key to be present at the named path.

1. SPIFFE workload identity — /var/run/secrets/spiffe.io/tls.{crt,key}. Resolved automatically when running as a Kubernetes pod with the SPIFFE CSI driver mounted; no explicit configuration needed.
2. Compiled-in client default — paths baked into crates/tls (tls_default::CLIENT_CERT / CLIENT_KEY). Used by binaries shipped onto x86 hosts or DPUs where the cert location is fixed.
3. In-repo dev certs — $REPO_ROOT/dev/certs/server_identity.{pem,key}. Used when developing against a local stack. REPO_ROOT must be set in the environment.

If none of those exist either, the CLI panics with the full enumerated list of where it looked. That message is the most reliable troubleshooting aid when a setup goes sideways — read it before guessing.

Logging

-d / --debug is a repeatable flag controlling the tracing level. The CLI writes logs to stderr, leaving stdout for command output:

Quick verification

Use version for a read-only connectivity check:

nico-admin-cli version

This command does not verify the server certificate, sends no client certificate, and is allowed anonymously. Success does not verify server trust, the client cert/key, or admin permissions. With credentials configured and DISABLE_TLS_ENFORCEMENT unset, use nico-admin-cli machine show to verify a protected, read-only operation. An empty inventory is also a valid result.

mTLS and authorization

For Vault-issued or operator-managed admin certificates, API trust and authorization, installation, renewal, CA overlap, recovery, and the existing revocation support boundary, see NICo mTLS and authorization.

For the full command reference, see the CLI manual.