Nepher CLI

The Nepher CLI (nepher-cli) is the unified command-line tool for Nepher Robotics — accounts, platform balance, tournaments, EnvHub, hackathons, and SimStore from a single install.

Repository: github.com/nepher-ai/nepher-cli · Current version: 0.2.6

Requires: Python 3.10+

Install

pip install -U nepher-cli

Both npcli and nepher-cli entry points are registered after install.

npcli --version
npcli --help

Tournament submission and coldkey registration sign with your local Bittensor keys. Install the lightweight wallet signer (full bittensor is not required):

pip install bittensor-wallet
# or: pip install "nepher-cli[bittensor]"

Upgrade to 0.2.6 or later

Since 0.2.3 the CLI talks to the unified API at https://api.nepher.ai. Version 0.2.6 adds submission-fee output and the account balance / account ledger commands. Older versions use retired API hosts — run pip install -U nepher-cli.

Command Overview

Command / Group	Description
npcli login	Log in with a Nepher API key
npcli whoami	Show the currently authenticated user
npcli logout	Clear locally stored credentials
npcli account	API keys, coldkey registration, platform balance and ledger
npcli tournament	Browse tournaments, check agents, submit, leaderboards
npcli envhub	Download, upload, and cache Isaac Lab environment bundles
npcli hackathon	Browse and submit to hackathons
npcli simstore	SimStore marketplace (coming soon)

Authenticate

npcli login --api-key nepher_xxxxxxxx   # or run `npcli login` and paste the key
npcli whoami
npcli logout

Create API keys at nepher.ai/account/api-keys. Keys are shown only once.

• login exchanges the API key for a session and stores credentials in your system keyring (or a local credentials file if no keyring is available).
• For CI/CD, set NEPHER_API_KEY=nepher_xxxxxxxx instead of logging in.
• Auth priority: --api-key / NEPHER_API_KEY → stored session → stored API key.
• npcli account login | logout | whoami are aliases of the top-level commands.

Tournaments

npcli tournament list [--active-only] [--limit 50] [--json]
npcli tournament list-active
npcli tournament status <tournament_id> [--json]
npcli tournament leaderboard <tournament_id> [--limit 20] [--json]

list-active prints each tournament's ID, task, current stage (upcoming, contest, submit, evaluation, review, reward, completed) and whether it accepts submissions.

Validate agent structure before submitting (no extra dependencies needed):

npcli tournament check --path ./my-agent
npcli tournament check --path ./my-agent --verbose   # also show recommended-file warnings

Required: best_policy/best_policy.pt and at least one task module under source/. Recommended: scripts/list_envs.py and scripts/rsl_rl/play.py.

Submit an Agent

npcli account balance        # make sure you can cover the submission fee
npcli tournament submit --path ./my-agent --wallet-name miner --wallet-hotkey default

Options for submit:

--path <path>                 Agent directory
--wallet-name <str>           Bittensor wallet name (default: miner)
--wallet-hotkey <str>         Bittensor wallet hotkey (default: default)
--api-key / --apikey <key>    Nepher API key (falls back to NEPHER_API_KEY / stored credentials)
--tournament-id <id>          Target tournament (required when several accept submissions)
--api-url <url>               Override the tournament API URL
-v / --verbose                Verbose output

The CLI zips the folder (skipping .git, logs, outputs, virtualenvs, caches, and .env), signs the archive hash with your hotkey, and uploads it. Before uploading it prints the submission fee and fee curve; after a successful upload it prints the Agent ID and the fee charged.

Requirements enforced by the API:

• Hotkey registered on Subnet 49
• Tournament within its contest/submit window
• Archive within the tournament's size limit (default 100 MB)
• Enough platform balance for the submission fee — otherwise the CLI shows "Submission fee failed" and suggests npcli account balance

See the Miner Guide for the full workflow.

Highlights (admin)

Tournament admins publish verified play videos with npcli tournament highlight:

npcli tournament highlight list [--tournament-id <id>] [--phase public|private] [--status draft|published]
npcli tournament highlight upload --tournament-id <id> --phase private --file run.mp4 --rank 1 [--poster poster.jpg] [--publish]
npcli tournament highlight publish <highlight_id>
npcli tournament highlight unpublish <highlight_id>
npcli tournament highlight delete <highlight_id>

Videos must be MP4 or WebM (max 100 MB); posters JPG, PNG, or WebP (max 10 MB). Rank and score are always read from the leaderboard.

Platform Balance

The platform balance (TAO) pays tournament submission fees and winner unlocks.

npcli account balance              # balance, registered coldkey, network
npcli account ledger --limit 50    # deposits, bonuses, fees, unlocks, adjustments

Deposits are made on-chain from your registered coldkey — see Platform Balance & Fees.

EnvHub

npcli envhub list [--category navigation] [--type usd|preset] [--benchmark] [--search <text>] [--json]
npcli envhub download <env_id> [--force] [--cache-dir <dir>]
npcli envhub upload ./my-bundle --category navigation [--thumbnail cover.png]
npcli envhub view <env_id> [--scene <name>]      # open in Isaac Lab (requires Isaac Lab)
npcli envhub cache list | info | clear [env_id] | migrate <new_path>
npcli envhub config get <key> | set <key> <value> | list | reset

Bundles are cached in ~/.nepher/cache by default (override with NEPHER_CACHE_DIR or --cache-dir). Upload directories must contain a manifest.yaml; they are zipped automatically. See EnvHub for platform details.

Hackathons

npcli hackathon list [--json]

npcli hackathon submit \
  --title "My entry" \
  --submission ./my-project \
  --assets ./my-assets

Options for submit:

--hackathon-id <uuid>       Required when multiple hackathons are open
--title <str>               Entry title (max 200 characters)
--description <markdown>    Entry description
--thumbnail <file>          Cover image (JPEG, PNG, WebP, GIF)
--submission <path>         Project folder or submission.zip
--assets <path>             Assets folder or assets.zip (images, videos, PDFs)
--public-source             Mark source as public
--api-key / --apikey <key>  Nepher API key with Hackathon access

The CLI runs a preflight check (file types, sizes, secret scanning) before uploading and prints your remaining upload quota. See Hackathons for submission requirements and voting.

Account & API Keys

API key management needs a session from npcli login. Do not pass --api-key on these commands — the account API rejects key management via X-API-Key.

npcli login --api-key nepher_...
npcli account api-keys list
npcli account api-keys create --name "CI key" --platform tournament --platform envhub [--expires-at 2027-01-01T00:00:00Z]
npcli account api-keys revoke <key_id>

Platforms: envhub, tournament, hackathon, simstore. Omit --platform for an unrestricted key.

Coldkey Registration

Bind a Bittensor coldkey to your Nepher account (required for platform deposits):

pip install bittensor-wallet
npcli account register-coldkey --wallet <wallet_name>

• Signing happens locally with bittensor-wallet; btcli is only used as a fallback.
• The API key used must include Hackathon access (or be unrestricted).
• Re-running with another wallet replaces your coldkey. A coldkey already bound to a different account is rejected.

API Key Requirements

• Must start with nepher_
• Must be active and not expired
• hackathon submit and account register-coldkey require Hackathon access (or an unrestricted key)
• For tournaments and EnvHub, an unrestricted key or one that includes Tournament / EnvHub access is recommended

Environment Variables

Variable	Purpose
NEPHER_API_KEY	API key used when not logged in (all commands)
NEPHER_API_URL	Unified API root (default https://api.nepher.ai)
NEPHER_ACCOUNT_API_URL, NEPHER_TOURNAMENT_API_URL, NEPHER_ENVHUB_API_URL, NEPHER_HACKATHON_API_URL	Per-product overrides (default <NEPHER_API_URL>/<product>)
NEPHER_CACHE_DIR	EnvHub cache directory (default ~/.nepher/cache)

Legacy: nepher-subnet Tools

The nepher-subnet repo provides the Docker-based validator. Its nepher-miner command is deprecated — use npcli tournament submit.

Tool	When to use
npcli	Everything for miners and users: login, balance, EnvHub, tournament submit, hackathons
nepher-validator / Docker	Running Subnet 49 validators (Validator Guide)
nepher-miner	Deprecated — kept for backward compatibility only

Troubleshooting

Error	Fix
npcli: command not found	Ensure pip install succeeded and Python scripts dir is on PATH
invalid api key format	Key must start with nepher_
api key does not have hackathon access	Enable Hackathon scope or use an unrestricted key
api key expired	Create a new key at nepher.ai/account/api-keys
Several hackathons are accepting submissions	Re-run with --hackathon-id
Multiple active tournaments exist	Re-run with --tournament-id (see npcli tournament list-active)
Submission fee failed / Insufficient platform balance	Check npcli account balance, then deposit on Account → Billing
Hotkey … is not registered on subnet 49	Register the hotkey with btcli subnet register --netuid 49
bittensor-wallet not installed	pip install bittensor-wallet (needed for tournament submit and account register-coldkey)
Not logged in	npcli login --api-key nepher_...
Conflict detected: 'scalecodec' ... conflicts with 'cyscale'	Leftover scalecodec from an old Bittensor install. pip install bittensor-wallet avoids needing btcli; to repair btcli: pip uninstall scalecodec cyscale -y && pip install -U cyscale --force-reinstall

Run any command with --help for full flag details:

npcli --help
npcli tournament submit --help
npcli hackathon submit --help

License

MIT — see nepher-cli LICENSE.