cli/

README

NICo CLI

Command-line client for the NVIDIA Infrastructure Controller (NICo) 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 NVIDIA Infrastructure Controller (NICo) REST API instance (local via make kind-reset or remote)

Installation

From the repo (recommended)

make nico-cli

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

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

With go install

go install ./cli/cmd/cli

Manual go build

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

Verify

nicocli --version

Quick Start

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

nicocli init                    # writes ~/.nico/config.yaml
cp ~/.nico/config.yaml ~/.nico/config.staging.yaml
cp ~/.nico/config.yaml ~/.nico/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:

nicocli tui

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

For direct one-off commands without the TUI:

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

Configuration

Config file: ~/.nico/config.yaml

nicocli init writes a sample matching the layout below.

api:
  base: http://localhost:8388
  org: test-org
  name: nico

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

  # Option 2: Auth script/token command
  # token_command: /path/to/get-nico-token.sh

  # Option 3: OIDC provider (e.g. Keycloak)
  oidc:
    token_url: http://localhost:8080/realms/nico-dev/protocol/openid-connect/token
    client_id: nico-api
    client_secret: nico-local-secret
    # Run `nicocli login` to authenticate; it will prompt for username/password
    # and persist the resulting bearer token (and refresh token) here.

  # Option 4: NGC API key
  # api_key:
  #   key: nvapi-xxxx
  #   # authn_url is only required for legacy NGC keys (without nvapi- prefix)
  #   # authn_url: https://your-authn-server/token

nicocli login writes bearer/refresh tokens back to this file, so restrict it (chmod 600 ~/.nico/config*.yaml) and do not commit it.

Global flags

These flags apply to every command and override the corresponding config values. Where an env var is listed, exporting it has the same effect as passing the flag.

Flag	Env Var	Description
--config	NICO_CONFIG	Path to the config file (defaults to ~/.nico/config.yaml)
--base-url	NICO_BASE_URL	API base URL
--org	NICO_ORG	Organization name
--token	NICO_TOKEN	Bearer token (skips login)
--token-command, --auth-script	NICO_TOKEN_COMMAND, NICO_AUTH_SCRIPT	Shell command/script that prints a bearer token on stdout
--token-url	NICO_TOKEN_URL	OIDC token endpoint URL for login and refresh
--keycloak-url	NICO_KEYCLOAK_URL	Keycloak base URL (constructs --token-url if not set)
--keycloak-realm	NICO_KEYCLOAK_REALM	Keycloak realm (default: nico-dev)
--client-id	NICO_CLIENT_ID	OAuth client ID (default: nico-api)
--debug		Log the full HTTP request and response for the call

Per-command flags

Output formatting and pagination flags live on individual commands, not on the root, so they go after the resource and action -- nicocli site list --output table, not nicocli --output table site list. The common ones:

Flag	Where	Description
--output	every command	Output format: json (default), yaml, table
--all	list commands	Fetch every page instead of just the first
--data	create/update commands	Request body as inline JSON
--data-file	create/update commands	Path to a JSON file (use - for stdin)

Run nicocli <command> --help for the full per-command flag list, including spec-derived query parameters and body fields.

Authentication

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

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

# OIDC client-credentials grant (no username -- use --client-secret)
nicocli --token-url https://auth.example.com/token login --client-secret "$NICO_CLIENT_SECRET"

# NGC API key (with explicit authn endpoint)
nicocli login --api-key nvapi-xxxx --authn-url https://your-authn-server/token

# Auth script/token command
nicocli --auth-script /path/to/get-nico-token.sh login

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

Tokens are saved to the active config file (~/.nico/config.yaml by default, or the path selected with --config / the TUI config selector). OIDC is refreshed when possible; TUI mode reruns the configured auth method after 401 Unauthorized API responses and retries safe read requests up to three times, logging each auth refresh/retry attempt.

login accepts these flags in addition to the OIDC/OAuth global flags above:

Flag	Env Var	Description
--username		Username for OIDC password grant
--password		Password for OIDC password grant (prompted if not provided)
--client-secret	NICO_CLIENT_SECRET	Client secret for confidential OIDC clients (also enables the client-credentials grant when no username is set)
--api-key	NICO_API_KEY	NGC API key to exchange for a bearer token
--authn-url	NICO_AUTHN_URL	NGC authentication URL for the API-key exchange

Usage

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

Command Structure

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

Spec Pattern	CLI Action
get-all-*	list
get-*	get
create-*	create
update-*	update
delete-*	delete
batch-create-*	batch-create
get-*-status-history	status-history
get-*-stats	stats

Nested API paths appear as sub-resource groups:

nicocli allocation list
nicocli allocation constraint list
nicocli allocation constraint create <allocationId>

Shell Completion

# Bash
eval "$(nicocli completion bash)"

# Zsh
eval "$(nicocli completion zsh)"

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

Multi-Environment Configs

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

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

The TUI automatically discovers all config*.yaml files in ~/.nico/ 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:

nicocli --config ~/.nico/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:

nicocli tui

You can also launch it with the i alias:

nicocli i

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

nicocli --config ~/.nico/config.prod.yaml tui

Troubleshooting

If nicocli 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:

nicocli --debug site list