| name | setup |
| description | Use when a first-time user needs help setting up inspire-cli configuration, or when troubleshooting config issues. Guides through credentials, project discovery, workspace binding, and verification. |
| allowed-tools | Bash(inspire *), Bash(uv run inspire *), Bash(uv run playwright *), Bash(mkdir *), Bash(ls *), Read, Write, Edit |
Inspire CLI Setup
Guide users through configuration by collecting info that can't be auto-detected.
Treat CLI help as source of truth (inspire --help, inspire <group> --help, inspire <group> <command> --help) — this doc can lag behind releases.
What's automated vs what needs user input
| Step | Automated | Needs user input |
|---|
| Project/workspace discovery | inspire init --discover | Username, password, base URL |
| Workspace aliases (cpu/gpu/internet) | Smart defaults in --discover | Confirmation or override |
target_dir | Catalog workdir as suggestion | Must verify via CPU notebook SSH |
| Project preference order | Nothing | Ranked list of project names |
| CPU/4090 notebook SSH | Fully automatic (rtunnel auto-downloaded and uploaded) | Nothing |
| GPU notebook SSH (no internet) | Automatic (rtunnel auto-uploaded) | apt_mirror_url or dropbear_deb_dir for SSH server |
| Bridge profile | inspire notebook ssh --save-as | Which notebook to use |
Setup flow
Phase 1: Credentials
Ask for base URL, username, password. Check env vars and global config first — skip if already present. Recommend INSPIRE_PASSWORD env var in shell profile (never commit passwords).
Phase 2: Discovery
Run inspire init --discover from the user's project working directory. Needs playwright (uv run playwright install chromium if missing).
If config files already exist, discovery prompts before rewrite; use --force for non-interactive runs.
After discovery: inspire config show and inspire config check to verify.
Phase 2b: Project preference
Show discovered projects from global config catalog. Ask user to rank by preference. Write project_order (list of project names) to [defaults] in project config.
Sort order when no --project flag: project_order (first match wins) > gpu_unlimited (tiebreaker) > priority > name. Projects not in the list sort after all listed ones.
Phase 2c: Verify paths via CPU notebook
Always do this. The catalog paths come from the API and can be wrong. CPU notebook SSH is guaranteed to work (zero setup needed) — use it as ground truth.
Always use --project explicitly when creating notebooks during setup. At this point project_order isn't configured yet, so auto-selection falls back to gpu_unlimited > priority which often picks the wrong project. Ask the user which project to use.
Create a CPU notebook, SSH in, explore the filesystem. Confirm:
shared_path_group — usually /inspire/hdd/global_user/<username>, visible across ALL projects.target_dir — usually /inspire/hdd/project/<slug>/<username>, project-specific workdir.
The CPU notebook can be stopped after verification — it is not needed for subsequent phases.
Phase 3: GPU SSH bootstrap (skip if CPU/4090 only)
GPU notebooks (H100/H200) have no internet. notebook ssh still works but needs an SSH server package installed on the notebook.
rtunnel is handled automatically. The CLI downloads rtunnel locally (~/.local/bin/rtunnel) and uploads it to each notebook via the Jupyter Contents API. No shared filesystem placement or CPU notebook needed.
SSH server requirement — one of:
apt_mirror_url — simpler, no pre-placed debs needed. Ask if the platform has an internal Ubuntu mirror (Nexus/Artifactory). Dropbear installed automatically via apt.dropbear_deb_dir — pre-place dropbear .deb packages on shared filesystem.
Both go in [ssh] section of project config.
Questions to ask:
- "Do you need GPU notebook SSH?" — skip if no
- "Does your platform have an internal APT mirror?" — determines
apt_mirror_url vs dropbear_deb_dir
Legacy option: rtunnel_bin in [ssh] config is still respected as highest priority if set. Users who already have rtunnel on shared filesystem do not need to change anything.
Phase 4: Bridge profile
inspire notebook ssh <id> --save-as <name> saves a reusable profile. Ask which notebook should be the default bridge — typically a CPU notebook for code sync/execution.
Bridge profiles break when notebooks restart. bridge exec/ssh auto-reconnect for notebook-backed profiles, but manually-added tunnels need manual recovery.
Troubleshooting (check in this order)
inspire config show — look for default source tags (means not configured), placeholder valuesinspire config check — validates auth, catches stale passwords- Missing
target_dir — most common cause of sync/bridge failures
- Wrong workspace — bridge/sync need CPU workspace (internet), jobs need GPU
- GPU SSH not working — needs either
apt_mirror_url or dropbear_deb_dir for SSH server installation. rtunnel is auto-uploaded and should not be the cause; check ~/.local/bin/rtunnel exists locally
- rtunnel upload failed — check Jupyter Contents API access; fallback: set
rtunnel_bin in [ssh] config pointing to a shared filesystem path
- Stale catalog — re-run
inspire init --discover to refresh
Reporting issues
If you encounter a setup problem you can't resolve (discovery failures, unexpected CLI behavior, missing features), suggest the user file an issue:
