hypha-cli

Command-line tool for managing Hypha Cloud resources — workspaces, server apps, and artifacts.

Installation

npm install -g hypha-cli

Requires Node.js >= 22 (for native WebSocket support).

Note: The Python hypha package also installs a hypha command. If you have both installed, use npx hypha-cli to run the Node.js CLI without conflicts.

Quick Start

# Login (opens browser for OAuth)
npx hypha-cli login

# Check workspace info
npx hypha-cli info

# List services
npx hypha-cli services

# List artifacts
npx hypha-cli artifacts ls

# Upload a file
npx hypha-cli artifacts cp ./data.csv my-model:data/train.csv

Configuration

Credentials are stored in ~/.hypha/.env:

HYPHA_SERVER_URL=https://hypha.aicell.io
HYPHA_TOKEN=<your-token>
HYPHA_WORKSPACE=<your-workspace>

You can also set these as environment variables, or use global flags:

npx hypha-cli --server https://hypha.aicell.io --workspace my-ws artifacts ls

Commands

Workspace Management

npx hypha-cli login [server-url]                    # OAuth login (opens browser)
npx hypha-cli token [--expires-in N] [--permission P] [--workspace W] [--json]
npx hypha-cli services [--type T] [--include-unlisted] [--json]
npx hypha-cli info [--json]

Apps — Server App Lifecycle

Manage server app definitions (like Docker images) and running instances (like containers).

npx hypha-cli apps list [--json]                    # List installed app definitions
npx hypha-cli apps info <app-id> [--json]           # Show app details
npx hypha-cli apps install <source> [--id ID] [--manifest P] [--files D...] [--overwrite]
npx hypha-cli apps uninstall <app-id>               # Remove app definition
npx hypha-cli apps start <app-id> [--timeout N] [--wait]  # Start instance
npx hypha-cli apps stop <id> [--all]                # Stop instance(s)
npx hypha-cli apps ps [--json]                      # List running instances
npx hypha-cli apps logs <instance-id> [--tail N] [--type T]

Aliases: ls = list, rm = uninstall

stop accepts either an instance ID or an app ID. With --all, stops all instances of that app.

Artifacts — Data & File Management

Linux-style commands for managing artifacts (datasets, models, files). Artifact paths use alias:path/to/file notation.

npx hypha-cli artifacts ls [artifact[:path]] [--json] [--long]
npx hypha-cli artifacts cat <artifact:path>
npx hypha-cli artifacts cp <src> <dest> [-r] [--commit]
npx hypha-cli artifacts rm <artifact[:path]> [-r] [--force]
npx hypha-cli artifacts create <alias> [--type T] [--parent P]
npx hypha-cli artifacts info <artifact> [--json]
npx hypha-cli artifacts search <query> [--type T] [--limit N] [--json]
npx hypha-cli artifacts commit <artifact> [--version V] [--message M]
npx hypha-cli artifacts edit <artifact> [--name N] [--description D]
npx hypha-cli artifacts discard <artifact>

Aliases: list = ls, mkdir = create, find = search

Shorthand: npx hypha-cli art = npx hypha-cli artifacts

Copy Examples

# Upload a single file
npx hypha-cli artifacts cp ./data.csv my-model:data/train.csv

# Download a file
npx hypha-cli artifacts cp my-model:weights.bin ./local/

# Upload a directory (recursive)
npx hypha-cli artifacts cp ./dataset/ my-model:data/ -r

# Upload and auto-commit
npx hypha-cli artifacts cp ./results.json my-model:results.json --commit

Programmatic API

import { connectToHypha, resolveServerUrl, resolveToken } from 'hypha-cli';
import { uploadFile, downloadFile } from 'hypha-cli';
import { parseArtifactPath, resolveArtifactId } from 'hypha-cli';

Development

# Build
yarn workspace hypha-cli build

# Run unit tests (176 tests)
yarn workspace hypha-cli test

# Run integration tests (requires HYPHA_TOKEN)
yarn workspace hypha-cli test:integration

# Dev mode (run from source)
yarn workspace hypha-cli dev -- artifacts ls

License

See LICENSE in the repository root.