muni 0.1.11

BioArena CLI — manage tools, jobs, spaces, and more

Muni CLI

Command-line interface for BioArena. Manage tools, GPU jobs, spaces, canvas nodes, and account balance from the terminal.

Zero external dependencies — stdlib only. Requires Python 3.11+.

Install

# Recommended — isolated global install
pipx install .

# Or for development
pip install -e .

Both install the muni command and the muni Python package. pipx is preferred for regular use — it installs into its own virtualenv but makes the muni binary available globally on PATH.

Quick Start

# 1. Log in (no config needed — defaults are built in)
# Default: opens a browser to muni.bio/cli/authorize, you click Authorize,
# CLI captures the callback on a localhost port, done. No password in terminal.
muni login

# On a headless / SSH box with no browser:
muni login --device
# Prints a short code; open muni.bio/device on any device and enter it.

# CI / scripted (legacy email+password):
muni login --email [e-mail] --password mypassword

# 3. Explore tools
muni tools
muni tools --category protein-design
muni tool bioarena_rfd3 --inputs

# 4. Run a job
muni run bioarena_rfd3 pdb_id=1UBQ num_designs=5
muni run bioarena_ipsae --batch ipsae_batch.jsonl
cat ipsae_batch.jsonl | muni run bioarena_ipsae --batch - --wait

# 5. Check status and get results
muni status job_<uuid>
muni results job_<uuid>
muni results job_<uuid> --fields sequence,iptm
muni results job_<uuid> --sequences
muni files job_<uuid>
muni download-all job_<uuid> -o ./results/
muni wait job_<uuid> job_<another-uuid>

# Or submit and wait in one step:
muni run bioarena_rfd3 pdb_id=1UBQ num_designs=5 --follow

# 6. Work with canvas nodes in a space
muni space use <space_id>
muni nodes
muni nodes search "PXDesign"
muni node show <node_id>
muni node show <node_id> --json

---

Job Identifiers

Every job the API creates has two IDs:

ID	Format	Purpose
job_id	job_<uuid>	DB primary key — the stable, provider-agnostic identifier. Shown first in all muni output. Prefer this.
call_id	bioarena-<tool>-job_<uuid> (Anyscale) or rw-<workflow-uuid> (Rowan)	External tracker the compute provider knows the job as. Useful for correlating with provider dashboards or webhooks.

All muni subcommands that take a job argument (status, results, files, logs, download, download-all, wait, job summary, job query) accept either form interchangeably — the API's getJob() branches on the job_ prefix. muni run prints Submitted: job_<uuid> by default; pass --json to see both fields.

---

Commands

Configuration

Command	Description
muni config	Interactive setup for API URL, Supabase URL, and publishable key
muni config show	Show the active config profile, including the active space (masks long keys)
muni config profiles	List all configured profiles and show which is active
muni config use <profile>	Switch the default profile (creates it if it doesn't exist)

Authentication

The CLI uses OAuth 2.0 against the muni app. The default flow is authorization code + PKCE with a localhost loopback — no password is ever typed in the terminal. Supabase Auth sits underneath; refresh tokens are scoped to this CLI installation and won't collide with web sessions.

Command	Description
muni login	Browser + PKCE flow (default). Opens <app_url>/cli/authorize, captures the callback on 127.0.0.1
muni login --device	RFC 8628 device code. Prints a code you enter at <app_url>/device on any device
muni login --no-browser	Print the authorize URL instead of launching a browser
muni login --client-name "My laptop"	Label the session in Connected Devices
muni login -e EMAIL -p PASS	Legacy email/password flow (CI/scripted use)
muni login --password-flow	Force the legacy flow with interactive prompts
muni logout	Revoke the CLI refresh token server-side and clear local credentials
muni whoami	Show current user email, user ID, profile name, credit balance, and active space

CLI sessions can be listed and revoked from the web at /account → Connected devices.

Account

Command	Description
muni balance	Show credit balance

Spaces

Spaces are shared workspaces for organizing jobs and collaborating with other users.

Command	Description
muni spaces	List your spaces and mark the active one
muni space create <name>	Create a new space
muni space delete <space_id>	Delete a space (owner only)
muni space members <space_id>	List members with email, role, and user ID
muni space invite <space_id> <email>	Invite a user to a space
muni space use <space_id-or-name>	Set the active space for canvas node commands

The active space is persisted in your profile config (~/.muni/config.json). Once set, all muni nodes and muni node commands default to it. You can override per-command with --space-id.

Canvas Nodes

Canvas nodes are the visual elements on a space's canvas — structures, metrics, file trees, code, text, and more. Each node has a type, label, optional node script (tool configuration), and lifecycle state.

Listing & Searching

Command	Description
muni nodes	List all canvas nodes in the active space
muni nodes --type structure	Filter by node type (structure, metric, filetree, text, code, json, markdown, image, molecule, note, results)
muni nodes -n 100	Set result limit (default: 50)
muni nodes --space-id <id>	Override the active space for this command
muni nodes search <query>	Search nodes by keyword (matches label, type, tool name, PDB ID, original name, text, markdown, SMILES, and metric columns)

muni nodes and muni nodes search now include canvas position, size, and connection count in both table and JSON output.

Inspecting

Command	Description
muni node show <node-or-entry-id>	Inspect a node by canvas node ID or entry ID
muni node show <node-or-entry-id> --script-only	Print only the raw node script payload
muni node show <node-or-entry-id> --json	Full node data as JSON, including connections and viz entry details

Creating

Command	Description
muni node create <label> --type <type>	Create a new canvas node
muni node create <label> --type <type> --script script.json	Create with a node script (tool configuration)
muni node create <label> --type <type> --space-id <id>	Create in a specific space

A node script is a JSON file describing what tool to run and how to display the result:

{
  "version": 1,
  "summary": "Fetch 1UBQ structure from RCSB",
  "toolName": "fetch_pdb",
  "executable": true,
  "primaryNodeType": "structure",
  "inputs": [{"key": "pdb_id", "value": "1UBQ", "source": "literal"}],
  "run": {
    "toolName": "fetch_pdb",
    "arguments": {"pdb_id": "1UBQ"}
  },
  "show": {"type": "structure"}
}

Updating & Running

Command	Description
muni node update <node_id> --script script.json	Update a node's script
muni node run <node_id>	Execute the node's tool (extracts run.toolName and run.arguments from the node script)
muni node run <node_id> --wait	Execute and wait for completion
muni node run <node_id> --follow	Execute with live status output
muni node run <node_id> --timeout 300	Set timeout in seconds (default: 1800)
muni node move <node-or-entry-id> --x 800 --y 200	Move a node to an absolute canvas position
muni node move <node-or-entry-id> --dx 150 --dy -40	Move a node relative to its current position

Deleting

Command	Description
muni node delete <node_id>	Remove a node from the canvas (soft-deletes the viz entry, deletes the canvas node row)

Note: Changes made via the CLI (creating, deleting nodes) are written directly to the database. If the space is open in the browser, you may need to refresh to see the changes. Real-time sync for CLI-originated mutations is planned for a future release.

muni node run uses the standard tools API for remote tools and a dedicated node-script bridge for local canvas tools like fetch_pdb, so structure-loader nodes can be executed directly from the CLI.

Connections

Command	Description
muni connections	List all canvas connections in the active space
muni connections --node-id <node_id>	List connections touching a specific node
muni connections --entry-id <entry_id>	List connections touching a specific entry
muni connection create --source-node-id A --target-node-id B	Create a connection with automatic handle selection
muni connection create --source-entry-id A --target-entry-id B --interaction-type metric-structure-gallery	Create a specialized metric-to-structure gallery connection
muni connection remove <connection_id>	Remove a connection

Typical workflow — explore a space from the terminal:

# Set your working space
muni space use 137df9fd-2634-4a99-bf7e-499799677d15

# See what's on the canvas
muni nodes
muni nodes --type metric
muni connections

# Search for a specific run
muni nodes search "PXDesign"
muni nodes search "2VSM"

# Inspect the binder design results
muni node show metric-pxdesign-binder-xxx --json | jq '.data.previewRows[] | {rank, af2_iptm, sequence}'

# Or get a human-readable summary
muni node show metric-pxdesign-binder-xxx

# Load a new structure node from RCSB
muni node create "1UBQ Structure" --type structure --script script.json
muni node run <node_id>

Tool Discovery

Command	Description
muni tools	List all available tools
muni tools -q <keyword>	Search tools by keyword
muni tools -c <category>	Filter by category (e.g. protein-design, peptide-science, structure-prediction)
muni tool <name>	Full tool info: description, category, reference URL, and all inputs
muni tool <name> --inputs	Input parameters table with types, defaults, required markers, and descriptions
muni tool <name> --examples	Usage examples with sample muni run commands

Job Execution

Command	Description
muni run <tool> [KEY=VALUE ...]	Submit a job. Returns the call_id immediately
muni run <tool> --params-file request.json	Load parameters from a JSON file
muni run bioarena_ipsae --batch batch.jsonl	Submit many IPSAE jobs from a JSONL file
cat batch.jsonl | muni run bioarena_ipsae --batch -	Submit a JSONL batch from stdin
muni run bioarena_ipsae --batch batch.jsonl --submit-concurrency 10	Set server-side batch submission concurrency
muni run <tool> ... --wait	Submit and poll until completion (prints compact completion hints)
muni run <tool> ... --follow	Submit and poll with richer live status output (provider, runtime)
muni run <tool> ... --timeout 300	Timeout in seconds for --wait/--follow (default: 1800)
muni run <tool> ... --space-id S	Associate job with a space
muni run <tool> ... --title "My run"	Set a human-readable job title
muni run <tool> ... --dry-run	Validate and print the resolved request payload without submitting
muni run <tool> ... --no-validate	Skip client-side schema validation before submitting
muni run <tool> ... --log-lines 200	Number of log tail lines to show after a failed --follow run (default: 120)

When using --wait or --follow, the CLI polls job status with escalating backoff (2s, 2s, 5s, 5s, then 10s intervals). In human mode, completion stays compact: instead of dumping huge result payloads, muni prints the result shape and the next useful command such as muni results <id> --fields ..., muni results <id> --sequences, or muni files <id>. On failure with --follow, the last N log lines are automatically shown.

Batch Submit

Batch submit is available in v1 for bioarena_ipsae.

Input format:

• JSONL only
• one JSON object per line
• each line must already contain the final tool arguments
• use --batch - to read JSONL from stdin

Examples:

# Submit 60 IPSAE jobs in one API request
muni run bioarena_ipsae --batch ipsae_batch.jsonl

# Submit from stdin
cat ipsae_batch.jsonl | muni run bioarena_ipsae --batch -

# Submit and wait for the successful items
muni run bioarena_ipsae --batch ipsae_batch.jsonl --wait --timeout 600

Behavior:

• Batch submission is best effort: valid items submit, invalid items are reported individually.
• --wait waits only on successfully submitted call IDs.
• exit code is non-zero if any batch item fails submission or any waited job fails/times out.
• --follow is not supported with --batch.
• shared Anyscale job queues are enabled automatically for batched IPSAE runs.

Job Monitoring

Command	Description
muni jobs	List recent jobs (default: 20 most recent)
muni jobs -s completed	Filter by status (submitted, running, completed, failed, cancelled)
muni jobs --space-id S	Filter by space
muni jobs -n 50	Set result limit
muni status <call_id>	Check job status (includes type, provider, runtime, timestamps)
muni wait <id1> <id2> ...	Poll one or more jobs until they finish
muni wait <id1> <id2> ... --json	Return a compact per-job summary for scripting
muni results <call_id>	Get job results as JSON (prints "still running" for 202 responses)
muni results <call_id> --fields sequence,iptm	Project selected fields from large structured result sets
muni results <call_id> --sequences	Extract sequences from common protein-design result shapes

muni wait and muni run --wait treat a job as finished when the job row reaches a terminal status (completed, failed, cancelled). In JSON mode, wait returns compact metadata such as status, job_type, updated_at, completed_at, and the detected result family, without embedding the full result payload.

Logs

Command	Description
muni logs <call_id>	Fetch provider logs (default: last 200 lines)
muni logs <call_id> --max-lines 500	Fetch more log lines
muni logs <call_id> --follow	Continuously poll logs until job reaches a terminal state
muni logs <call_id> --follow --interval 10	Set polling interval in seconds (default: 5)

File Management

Command	Description
muni files <call_id>	List output files as a tree (with file sizes)
muni files <call_id> --path designs	Show only the designs/ subtree
muni download <call_id> <path>	Download a single file (saves to current directory)
muni download <call_id> <path> -o out.pdb	Download with a custom output path
muni download <call_id> <path> --stdout	Write a single file directly to stdout
muni download <call_id> <path> -o -	Alias for --stdout
muni download <call_id> designs	Download an entire directory (auto-detected)
muni download-all <call_id>	Download all files to ./<call_id>/
muni download-all <call_id> -o ./results/	Download all to a custom directory
muni download-all <call_id> --path designs	Download only the designs/ folder
muni download-all <call_id> --glob "*.pdb"	Download only .pdb files
muni download-all <call_id> -p designs -g "*.json"	Combine: only .json files under designs/

Binary files are base64-decoded on download. Text files are written as UTF-8.

Use --stdout only for single files. It is designed for piping into tools like jq, head, and grep, and cannot be combined with --json.

Typical workflow — inspect then download:

# See what the job produced
muni files job_<uuid>

# Download just the designs folder
muni download-all job_<uuid> --path designs -o ./my-designs/

# Or grab only PDB files from anywhere in the output
muni download-all job_<uuid> --glob "*.pdb" -o ./structures/

# Or stream one file directly into another tool
muni download job_<uuid> summary.json --stdout | jq '.'

---

Global Flags

These flags work with any subcommand:

Flag	Description
--json	Output machine-readable JSON instead of human-formatted tables
--profile <name>	Use a specific config/credentials profile for this command
--api-url <url>	Override the API URL for this command only
--supabase-url <url>	Override the Supabase URL for this command only
--supabase-publishable-key <key>	Override the Supabase publishable key for this command only

Examples: muni config show --json muni space members <space_id> --json

---

Parameter Syntax

Parameters use KEY=VALUE format on the command line. Values are auto-parsed:

# Strings
muni run bioarena_rfd3 pdb_id=1UBQ

# Numbers (auto-detected via JSON parsing)
muni run bioarena_rfd3 pdb_id=1UBQ num_designs=10

# Booleans
muni run some_tool flag=true

# JSON arrays
muni run bioarena_rfd3 hotspot_residues='["A32","A35"]'

# JSON objects
muni run some_tool config='{"key": "value"}'

File References

Use @ to load parameter values from files:

# Auto-detect: JSON files parsed as JSON, others read as text
muni run bioarena_rfd3 target_pdb=@./my_protein.pdb
muni run bioarena_protenix input_json=@./request.json

# Force JSON parsing
muni run bioarena_protenix input_json=@json:./request.json

# Force text (no JSON parsing)
muni run bioarena_rfd3 target_pdb=@text:./target.pdb

Params File

Load all parameters from a JSON file (can be combined with KEY=VALUE args, which take precedence):

muni run bioarena_protenix --params-file ./request.json
muni run bioarena_protenix --params-file ./request.json num_designs=20  # override

Client-Side Validation

By default, muni run fetches the tool's JSON Schema and validates parameters locally before submitting. This catches type mismatches, unknown parameters, and missing required fields. Disable with --no-validate.

--validate here is client-side schema validation only. It does not perform a remote execution preflight against staged files or backend job readiness.

Result Shapes

Different tools store different result families in Supabase. Common shapes include:

• record arrays such as rankings, top_designs, sequences, designs, and some array-shaped metrics
• scorecard objects such as best_metrics, metrics_summary, ranking, object-shaped metrics, and object-shaped summary
• file-heavy manifests such as pdb_files, summary_files, csv_files, json_files, and related output lists

muni results --fields works best for structured record arrays and scorecard objects. muni results --sequences is a convenience extractor for common protein-design outputs. For file-heavy jobs, start with muni files and then muni download or muni download-all.

---

Configuration

Config is stored in ~/.muni/config.json with named profile support:

{
  "current_profile": "default",
  "profiles": {
    "default": {
      "api_url": "https://api.bioarena.com",
      "supabase_url": "https://xxx.supabase.co",
      "supabase_publishable_key": "sb_publishable_..."
    },
    "local": {
      "api_url": "http://localhost:8000",
      "supabase_url": "https://xxx.supabase.co",
      "supabase_publishable_key": "sb_publishable_..."
    }
  }
}

Credentials are stored separately in ~/.muni/credentials.json per profile. Both files are created with 0600 permissions.

Environment Variables

Environment variables override config file values:

Variable	Description
MUNI_API_URL	BioArena Tools API URL
MUNI_SUPABASE_URL	Supabase project URL
MUNI_SUPABASE_PUBLISHABLE_KEY	Supabase publishable key
MUNI_SPACE_ID	Override the active space for canvas node commands
MUNI_PROFILE	Select a saved config/credentials profile

Token Management

Authentication tokens are automatically refreshed when within 60 seconds of expiry. If the refresh token is missing or invalid, you'll need to muni login again.

---

Python SDK

Use MuniClient programmatically for scripting and automation:

from muni import MuniClient

client = MuniClient()

# List tools
tools = client.list_tools(category="protein-design")

# Run a job
result = client.run("bioarena_rfd3", {"pdb_id": "1UBQ", "num_designs": 5})
call_id = result["call_id"]

# Run a batch of jobs
batch = client.run_batch(
    "bioarena_ipsae",
    [
        {"pae_content": "...", "structure_content": "..."},
        {"pae_content": "...", "structure_content": "..."},
    ],
    title_prefix="IPSAE batch",
)
call_ids = batch["call_ids"]

# Wait for completion (with optional status callback)
def on_status(data):
    print(f"Status: {data['status']}")

results = client.wait_for_job(call_id, timeout=600, on_status=on_status)

# Check individual job status
status = client.job_status(call_id)

# Get logs
logs = client.job_logs(call_id, max_lines=200)

# Download files
files = client.list_files(call_id)
client.save_file(call_id, "designs/design_1.pdb", "./design_1.pdb")
client.save_all_files(call_id, "./output/")

# Download only a subfolder
client.save_all_files(call_id, "./designs/", path_prefix="designs")

# Download only PDB files
client.save_all_files(call_id, "./structures/", glob_pattern="*.pdb")

# Combine: PDB files from the designs folder
client.save_all_files(call_id, "./out/", path_prefix="designs", glob_pattern="*.pdb")

# Canvas nodes
nodes = client.list_nodes(space_id, node_type="metric")
results = client.search_nodes(space_id, "PXDesign")

node = client.get_node(node_id)
print(node["data"]["label"])
print(node["data"]["previewRows"])  # metric data

# Create a node with a script
script = {
    "version": 1,
    "summary": "Fetch 1UBQ",
    "toolName": "fetch_pdb",
    "executable": True,
    "primaryNodeType": "structure",
    "inputs": [{"key": "pdb_id", "value": "1UBQ", "source": "literal"}],
    "run": {"toolName": "fetch_pdb", "arguments": {"pdb_id": "1UBQ"}},
    "show": {"type": "structure"},
}
node = client.create_node(space_id, "1UBQ Structure", "structure", node_script=script)

# Run the node's tool
result = client.run_node(node["id"])

MuniClient Methods

Method	Returns	Description
list_tools(query, category)	dict	List/search available tools
get_tool(name)	dict	Get tool schema and details
get_examples(name)	dict	Get usage examples for a tool
run(tool, args, space_id, title)	dict	Execute a tool, returns {"call_id": "..."}
run_batch(tool, items, space_id, title_prefix, submit_concurrency)	dict	Execute many items in one API request
job_status(call_id)	dict	Check job status
job_results(call_id)	(int, dict)	Get results (HTTP status 202 = still running)
job_logs(call_id, max_lines)	dict	Fetch provider logs
wait_for_job(call_id, timeout, on_status)	dict	Poll until completion, raises on failure/timeout
list_jobs(space_id, status, limit)	list[dict]	List jobs from Supabase
list_files(call_id)	dict	List output files
download_file(call_id, path)	(str, bool)	Download file content (content, is_text)
save_file(call_id, path, dest)	Path	Download and write file to disk
save_all_files(call_id, output_dir, *, path_prefix, glob_pattern)	list[Path]	Download files, optionally filtered by directory or glob
get_balance()	dict	Get credit balance
list_spaces()	list[dict]	List user's spaces
create_space(name)	dict	Create a space
delete_space(space_id)	None	Delete a space
space_members(space_id)	list[dict]	List space members
invite_to_space(space_id, email)	str	Invite user to a space
resolve_space_id(id_or_name)	str	Resolve a space UUID or name to a UUID
list_nodes(space_id, *, node_type, limit)	list[dict]	List canvas nodes in a space
search_nodes(space_id, query, *, limit)	list[dict]	Search canvas nodes by keyword
get_node(node_id)	dict	Get a single canvas node by ID
get_viz_entry(entry_id)	dict | None	Get a viz entry by ID
create_node(space_id, label, node_type, *, node_script)	dict	Create a canvas node with optional node script
update_node(node_id, data_updates)	dict	Update a node's data (merge into JSONB)
run_node(node_id, *, space_id)	dict	Execute the node's tool from its node script
delete_node(node_id)	None	Soft-delete viz entry + delete canvas node

Exceptions

from muni import MuniError, AuthError, NotFoundError, JobFailedError, JobTimeoutError
from muni.exceptions import APIError, JobCancelledError

try:
    results = client.wait_for_job(call_id, timeout=300)
except JobFailedError as e:
    print(f"Job {e.call_id} failed: {e.error}")
except JobTimeoutError as e:
    print(f"Job {e.call_id} didn't finish in {e.timeout}s")
except JobCancelledError as e:
    print(f"Job {e.call_id} was cancelled")
except AuthError:
    print("Not logged in or token expired")

Exception	Description
MuniError	Base class for all muni errors
AuthError	Login failed or no valid credentials
NotFoundError	Tool, job, or file not found
APIError	Unexpected HTTP error (has .status_code)
JobFailedError	Job completed with failed status (has .call_id, .error)
JobCancelledError	Job was cancelled (has .call_id)
JobTimeoutError	Timed out waiting for job (has .call_id, .timeout)

---

Architecture

The CLI has two backends:

1. Tools API (Elysia server) — tool discovery, execution, job status/results/files/logs
2. Supabase PostgREST (direct) — auth, spaces, balance, job listing, canvas nodes

muni login    →  Supabase Auth API  →  ~/.muni/credentials.json
muni run      →  Tools API (POST /tools/:name/execute, bearer-authenticated)
muni status   →  Tools API (GET /jobs/:callId/status)
muni spaces   →  Supabase PostgREST (GET /rest/v1/spaces)
muni jobs     →  Supabase PostgREST (GET /rest/v1/jobs)
muni nodes    →  Supabase PostgREST (GET /rest/v1/canvas_nodes)
muni node     →  Supabase PostgREST (GET/POST/PATCH/DELETE /rest/v1/canvas_nodes + viz_entries)

All HTTP is stdlib urllib — no external dependencies.

Project Structure

muni-cli/
├── muni/
│   ├── __init__.py       # MuniClient + exceptions re-export
│   ├── __main__.py       # python -m muni entry point
│   ├── cli.py            # argparse subcommands + KEY=VALUE parsing
│   ├── client.py         # MuniClient high-level methods
│   ├── auth.py           # Login, logout, token refresh
│   ├── api.py            # Tools API HTTP calls
│   ├── supabase.py       # PostgREST + Auth HTTP calls
│   ├── display.py        # Human-readable formatting (tables, trees, status)
│   ├── config.py         # ~/.muni/ file management + profile switching
│   └── exceptions.py     # MuniError hierarchy
├── pyproject.toml        # PEP 621 packaging (setuptools)
├── scripts/push          # Version-bumping push script
└── README.md

Versioning

Version is defined in muni/__init__.py (__version__) and read dynamically by pyproject.toml. Check it with:

muni --version

Auto-bump on push

Use ./scripts/push instead of git push to automatically bump the patch version after a successful push:

./scripts/push origin master

This will:

1. Push your commits
2. Bump the patch version (e.g. 0.1.3 → 0.1.4)
3. Commit and push the version bump

For major or minor bumps, edit muni/__init__.py manually before pushing.