Inspire CLI

Command-line interface for the Inspire HPC training platform.

Installation

# Via SSH (recommended)
uv tool install git+ssh://git@github.com/EmbodiedForge/Inspire-cli.git

# Or via HTTPS
uv tool install git+https://github.com/EmbodiedForge/Inspire-cli.git

Local Development

uv tool install -e .
inspire --help

Zsh Completion

inspire uses Click's native shell completion. On zsh, the clean setup is the standard fpath + compinit flow, the same model many mature CLIs use.

1. Make sure your ~/.zshrc adds a personal completion directory before compinit:

fpath=($HOME/.zsh/completions $fpath)
autoload -Uz compinit
compinit

2. Generate the completion function once:

mkdir -p ~/.zsh/completions
_INSPIRE_COMPLETE=zsh_source inspire > ~/.zsh/completions/_inspire

3. Reload your shell:

exec zsh

Notes:

• oh-my-zsh is not required.
• Completion stays local-config-driven through Click shell_complete= hooks.
• For local development, you can replace inspire with uv run inspire when generating _inspire.

Quick Start

1. Auto-discover your platform

inspire init --discover -u YOUR_USERNAME --base-url https://your-platform.com

This opens a browser to log in, then automatically discovers your projects, workspaces, compute groups, and shared filesystem paths. Writes both global (~/.config/inspire/config.toml) and project (.inspire/config.toml) configs.

Set your password as an env var to avoid repeated prompts:

export INSPIRE_PASSWORD="your_password"

2. Verify

inspire config show    # Check all values resolved
inspire config check   # Validate API auth

3. Start using

inspire resources list          # View GPU availability
inspire notebook create --name dev --resource 4xCPU --wait
inspire notebook ssh <id>       # SSH into notebook (auto-installs tunnel)

Commands

Command	Description
inspire job create	Submit a training job
inspire job status/logs/list	Monitor and manage jobs
inspire job stop/wait	Stop or wait for a job
inspire run "<cmd>"	Quick job with auto resource selection
inspire sync	Sync code to shared filesystem (via SSH tunnel)
inspire bridge exec "<cmd>" [--stdin]	Run command on Bridge runner
inspire bridge ssh [--bridge <name>]	Interactive SSH shell to a Bridge profile
inspire bridge scp <source> <destination>	Upload/download files via Bridge tunnel
inspire notebook list	List notebooks (supports --columns, --tunneled, --json)
inspire notebook create	Create a notebook instance
inspire notebook start/stop	Start or stop a notebook
inspire notebook ssh <id>	SSH into notebook (sets up tunnel)
inspire notebook top	Show GPU utilization/memory for tunnel-backed notebooks
inspire image list/detail	Browse Docker images
inspire image save/register	Save or register custom images
inspire tunnel add/list/status	Manage SSH tunnels to Bridge
inspire tunnel ssh-config	Generate SSH config for direct access
inspire project list	View projects and GPU quota
inspire resources list/nodes	View GPU availability
inspire config show/check	Inspect and validate configuration
inspire init	Generate starter config from env vars
inspire init --discover	Auto-discover projects, workspaces, compute groups

Global Flags:

• --json - Output in JSON format (useful for scripting)

Examples

# Submit a training job
inspire job create --name "train-v1" --resource "4xH200" --command "bash train.sh"

# Quick run with auto-selected resources, sync code and follow logs
inspire run "python train.py --epochs 100" --sync --watch

# Sync code and verify
inspire sync && inspire bridge exec "git log -1"

# Stream local stdin to remote command (no heredoc quoting hacks)
inspire bridge exec --bridge mybridge --stdin -- bash -s < scripts/watch_eval.sh

# Set up SSH tunnel to a notebook
inspire notebook ssh <notebook-id> --save-as mybridge
ssh mybridge

# Check live GPU usage for all saved notebook tunnels
inspire notebook top
inspire notebook top --bridge mybridge --watch

# Copy files through a configured bridge profile
inspire bridge scp ./model.py /tmp/model.py --bridge mybridge
inspire bridge scp -d /tmp/checkpoints/ ./checkpoints/ -r --bridge mybridge

# Check GPU availability and project quota
inspire resources list
inspire project list

# List notebooks with custom columns (show tunnel status)
inspire notebook list -c name,status,tunnel

# Show only notebooks with active SSH tunnels
inspire notebook list --tunneled -n 10

# JSON output for scripting
inspire notebook list --json
inspire job list --json

SSH/SCP Reliability Notes

• There is no inspire tunnel start command. Create or refresh bridge profiles with inspire notebook ssh <notebook-id> --save-as <name> (or inspire tunnel add / inspire tunnel update), then validate with inspire tunnel status.
• inspire bridge ssh and inspire bridge scp validate --bridge names before connectivity checks. If a profile is missing, run inspire tunnel list.
• inspire bridge exec --stdin -- <remote command> forwards local stdin to the remote process over SSH.
• Saved notebook profiles now store the source notebook ID. Reusing --save-as <name> for a different notebook refreshes the tunnel instead of reusing stale tunnel state.
• inspire bridge ssh, inspire bridge exec, and interactive inspire notebook ssh auto-rebuild/reconnect dropped tunnels for notebook-backed profiles, using tunnel.retries / tunnel.retry_pause as retry controls.
• Non-notebook tunnel profiles (for example, manually added profiles without notebook_id) cannot be auto-rebuilt and still require manual tunnel recovery.
• inspire tunnel ssh-config now writes shell-quoted ProxyCommand entries so proxy URLs with query parameters/tokens remain safe in ~/.ssh/config.

Configuration

The recommended way to configure is inspire init --discover, which auto-detects projects, workspaces, compute groups, and writes config files.

Config files are loaded in order (later overrides earlier):

1. Global: ~/.config/inspire/config.toml
2. Project: ./.inspire/config.toml
3. Environment variables

Account password lookup follows the same layered model:

1. [accounts."<username>"].password from global config
2. [accounts."<username>"].password from project config (overrides global for same username)
3. INSPIRE_PASSWORD (fallback only if no account password was found)

Legacy [auth].password is still supported, but account passwords take precedence when both are present.

Run inspire init --discover to auto-configure, or inspire config show to inspect the merged result.

inspire init probe-only options are effective only with --discover --probe-shared-path: --probe-limit, --probe-keep-notebooks, --probe-pubkey/--pubkey, and --probe-timeout. Without that combination, they are accepted but ignored.

Example config.toml:

[auth]
username = "your_username"

[accounts."your_username"]
# Optional: supports multi-account setups in global and/or project config
password = "your_password"

[api]
base_url = "https://your-inspire-platform.com"

[bridge]
# Timeout in seconds for `inspire bridge exec`
action_timeout = 600

[defaults]
# Shared fallback settings for jobs and notebooks
# resource = "1xH200"
# image = "pytorch:latest"
# priority = 6
# shm_size = 32
# project_order = ["cq", "ci"]

[job]
# resource = "4xH200"
# project_id = "project-..."
# image = "pytorch:latest"
# priority = 6
# shm_size = 32

[notebook]
# resource = "1xH200"
# project_id = "project-..."
# image = "pytorch:latest"
# priority = 6
# shm_size = 32
# post_start = "bash /workspace/bootstrap.sh"

[remote_env]
# Exported before bridge exec, job commands, and notebook post-start commands/scripts.
# PIP_INDEX_URL = "https://mirror.example/simple"
# APT_MIRROR_URL = "http://nexus.example.com/repository/ubuntu/"

[workspaces]
# cpu = "ws-..."       # Default workspace (CPU jobs / notebooks)
# gpu = "ws-..."       # GPU workspace (H100/H200 jobs)
# internet = "ws-..."  # Internet-enabled GPU workspace (e.g. RTX 4090)
# special = "ws-..."   # Custom alias (use with --workspace special)

[[compute_groups]]
name = "H100 Cluster"
id = "lcg-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
gpu_type = "H100"

[ssh]
# For GPU notebooks (H100/H200) without internet:
# rtunnel_bin = "/inspire/shared/tools/rtunnel"
# Option A: APT mirror (simpler — no pre-placed debs needed)
# apt_mirror_url = "http://nexus.example.com/repository/ubuntu/"
# Option B: Pre-placed dropbear debs
# dropbear_deb_dir = "/inspire/shared/debs/dropbear"

Use [remote_env] for package-manager env vars such as PIP_INDEX_URL when your remote shell or notebook post-start installs packages. For notebook SSH bootstrap on offline GPU notebooks, ssh.apt_mirror_url remains the explicit setting, and remote_env.APT_MIRROR_URL is also accepted as a fallback.

View current config:

inspire config show
inspire config show --json
inspire config check   # Validate config + API auth
inspire --json config check
inspire config check --json
inspire init --json --template --project --force

Environment Variables

Variable	Description
INSPIRE_USERNAME	Platform username
INSPIRE_PASSWORD	Platform password
INSPIRE_BASE_URL	API base URL
INSPIRE_TARGET_DIR	Shared filesystem path
INSPIRE_DEFAULT_RESOURCE	Shared default resource for jobs and notebooks
INSPIRE_DEFAULT_IMAGE	Shared default image for jobs and notebooks
INSPIRE_DEFAULT_PRIORITY	Shared default priority for jobs and notebooks
INSPIRE_PROJECT_ORDER	Project preference order for automatic selection
INSPIRE_SHM_SIZE	Shared default shared memory size
INSPIRE_WORKSPACE_CPU_ID	CPU workspace ID (default workspace)
INSPIRE_WORKSPACE_GPU_ID	GPU workspace ID (H100/H200)
INSPIRE_WORKSPACE_INTERNET_ID	Internet-enabled workspace ID (e.g. RTX 4090)
INSPIRE_JOB_RESOURCE	Job-specific default resource
INSPIRE_PROJECT_ID	Default project ID
INSP_IMAGE	Default Docker image
INSP_PRIORITY	Job priority (1-10)
INSPIRE_NOTEBOOK_PROJECT_ID	Notebook-specific default project ID
INSPIRE_APT_MIRROR_URL	APT mirror URL for offline notebook SSH bootstrap