cli/

Carbide CLI

Command-line client for the NCX Infra Controller REST API. Commands are dynamically generated from the embedded OpenAPI spec at startup, so every API endpoint is available with zero manual command code.

Prerequisites

• Go 1.25.4 or later
• Access to a running NCX Infra Controller REST API instance (local via make kind-reset or remote)

Installation

From the repo (recommended)

make carbide-cli

This builds and installs carbidecli to $(go env GOPATH)/bin/carbidecli. Override the destination with:

make carbide-cli INSTALL_DIR=/usr/local/bin

With go install

go install ./cli/cmd/carbidecli

Manual go build

go build -o /usr/local/bin/carbidecli ./cli/cmd/carbidecli

Verify

carbidecli --version

Quick Start

Generate a default config and add configs for each environment you work with:

carbidecli init                    # writes ~/.carbide/config.yaml
cp ~/.carbide/config.yaml ~/.carbide/config.staging.yaml
cp ~/.carbide/config.yaml ~/.carbide/config.prod.yaml

Edit each file with the appropriate server URL, org, and auth settings for that environment (see Configuration below), then launch interactive mode:

carbidecli tui

The TUI will list your configs, let you pick an environment, authenticate, and start running commands. This is the recommended way to use carbidecli since it handles environment selection, login, and token refresh automatically.

For direct one-off commands without the TUI:

carbidecli login                   # exchange credentials for a token
carbidecli site list               # list all sites

Configuration

Config file: ~/.carbide/config.yaml

api:
  base: http://localhost:8388
  org: test-org
  name: carbide                # API path segment (default)

auth:
  # Option 1: Direct bearer token
  # token: eyJhbGciOi...

  # Option 2: OIDC provider (e.g. Keycloak)
  oidc:
    token_url: http://localhost:8080/realms/carbide-dev/protocol/openid-connect/token
    client_id: carbide-api
    client_secret: carbide-local-secret

  # Option 3: NGC API key
  # api_key:
  #   authn_url: https://authn.nvidia.com/token
  #   key: nvapi-xxxx

Flags and environment variables override config values:

Authentication

# OIDC (credentials from config, prompts for password if not stored)
carbidecli login

# OIDC with explicit flags
carbidecli --token-url https://auth.example.com/token login --username admin@example.com

# NGC API key
carbidecli login --api-key nvapi-xxxx

# Keycloak shorthand
carbidecli --keycloak-url http://localhost:8080 login --username admin@example.com

Tokens are saved to ~/.carbide/config.yaml with auto-refresh for OIDC.

Usage

carbidecli site list
carbidecli site get <siteId>
carbidecli site create --name "SJC4"
carbidecli site create --data-file site.json
cat site.json | carbidecli site create --data-file -
carbidecli site delete <siteId>
carbidecli instance list --status provisioned --page-size 20
carbidecli instance list --all                # fetch all pages
carbidecli allocation constraint create <allocationId> --constraint-type SITE
carbidecli site list --output table
carbidecli --debug site list

Command Structure

Commands follow carbidecli <resource> [sub-resource] <action> [args] [flags].

Nested API paths appear as sub-resource groups:

carbidecli allocation list
carbidecli allocation constraint list
carbidecli allocation constraint create <allocationId>

Shell Completion

# Bash
eval "$(carbidecli completion bash)"

# Zsh
eval "$(carbidecli completion zsh)"

# Fish
carbidecli completion fish > ~/.config/fish/completions/carbidecli.fish

Multi-Environment Configs

Each environment (local dev, staging, prod) gets its own config file in ~/.carbide/:

~/.carbide/config.yaml           # default (local dev)
~/.carbide/config.staging.yaml   # staging
~/.carbide/config.prod.yaml      # production

The TUI automatically discovers all config*.yaml files in ~/.carbide/ and presents them as a selection list at startup. This is the easiest way to switch between environments without remembering URLs or re-authenticating.

For direct commands, select an environment with --config:

carbidecli --config ~/.carbide/config.staging.yaml site list

Interactive TUI Mode

The TUI is the recommended way to interact with the API. It handles config selection, authentication, and token refresh in one session:

carbidecli tui

You can also launch it with the i alias:

carbidecli i

To skip the config selector and connect to a specific environment directly:

carbidecli --config ~/.carbide/config.prod.yaml tui

Troubleshooting

If carbidecli is not found after install, make sure $(go env GOPATH)/bin is in your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Use --debug on any command to see the full HTTP request and response for diagnosing issues:

carbidecli --debug site list