OpenCosmo Portal CLI (ocp)

Command-line client and local MCP server for the OpenCosmo Portal: query cosmological simulation datasets at DOE Leadership Computing Facilities from your terminal or from an AI assistant.

pip install opencosmo-portal      # in a checkout: cd cli && uv sync, then prefix commands with `uv run`

Quick start

ocp auth login                    # Globus device-code flow; --browser for a local redirect flow
ocp task list
ocp task info <slug>
ocp task run <slug>               # interactive; or --input/--file JSON
ocp run status <run-id> --watch
ocp run results <run-id>

Shipped profiles: production (https://cosmoexplorer.alcf.anl.gov, default), staging (https://opencosmo-test.cels.anl.gov, internal network), dev (http://localhost:8000). Pass --profile <name> or set a default with ocp config set-profile. Shipped profiles cannot be removed but their URLs can be overridden with ocp config add-profile; former official URLs migrate automatically on upgrade, overrides are kept.

Config and tokens live in ~/.opencosmo/ (config.json, tokens/<profile>.json). Output is table or --format json. After interactive commands the CLI checks PyPI for a newer release at most once per 24 h and shows active portal announcements (outages, new features, deprecations) cached for 5 minutes per portal — both stderr-only, bounded by a shared one-second deadline, and never affecting the command. OPENCOSMO_DISABLE_UPDATE_CHECK=1 and OPENCOSMO_DISABLE_ANNOUNCEMENTS=1 turn them off. ocp announcements lists active announcements on demand.

Commands

ocp --help and ocp <group> --help list everything. Overview:

Interactive ocp task run shows leaf fields of the task's nested input as a numbered table with their currently active constraints, re-evaluates the schema's conditional rules after every edit (repairing or flagging values that became invalid), and validates the complete input against the task schema before submitting. --input/--file payloads are validated as supplied, with no repair. ocp task info lists parameters by dotted path (filters.sod_halo_mass.minval), matching the nested JSON those options take.

ocp run status renders the server's run-diagnostics projection (failure code and phase, guidance, warnings, bounded traceback, evidence state, correlation IDs); against an older server it falls back to the summary view.

MCP server for AI assistants

ocp mcp start

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": { "opencosmo": { "command": "ocp", "args": ["mcp", "start"] } }
}

This stdio server supports both legacy and modern MCP handshakes and calls the portal API with the profile's CLI token. It is distinct from the hosted remote endpoint at <portal-origin>/mcp, which is modern-protocol-only and has its own OAuth token; ocp auth logout does not clear a remote MCP client's token.

Administration

All ocp admin commands require admin permissions. For CI, set OPENCOSMO_API_URL and OPENCOSMO_API_KEY (a service-account key); the CLI exchanges the key for a JWT per run and persists neither. OPENCOSMO_API_KEY takes precedence over stored profile tokens.

Content deployment — categories, datasets, task adapters, and user docs are complete desired-state payloads. Each command accepts dir <path>, url <archive-url> --subdir <dir> (--header "PRIVATE-TOKEN:..."), or gitlab --host --project --ref --job --subdir [--gitlab-token-env]; archives may be .zip, .tar, .tar.gz, .tgz. Discovery is non-recursive: only direct children of the selected directory are read (for tasks, *.json; for docs, Markdown at the root plus one subdirectory level, root index.md required — pass the directory containing index.md inside a docs checkout or extracted artifact, not the checkout root). Deploy in this order:

ocp admin tasks categories sync build/categories.json --yes
ocp admin datasets sync build/datasets.json --yes
ocp admin tasks install dir build/tasks --strict
ocp admin docs deploy dir <docs-checkout>/content/documentation --yes

Every command dry-runs server-side first and shows the planned create/update/delete actions; without --yes it asks for confirmation (defaulting to no when anything would be deleted). tasks install --strict exits 1 on any warning (for example an unregistered category slug) before sending real installs; installs are idempotent, so re-running after fixing the registry is safe. Dataset sync validates binding tags, so task installs fail on a fresh instance until datasets are synced; deleting a dataset that installed tasks still reference warns rather than fails.

Service accounts:

ocp admin service-accounts create ci-task-manager --profile task-manager --description "CI"
ocp admin service-accounts rotate-key ci-task-manager      # create/rotate print the key once
ocp admin service-accounts revoke-key ci-task-manager KEY_ID --yes
ocp admin service-accounts disable ci-task-manager --yes

Enabled service accounts are valid through urn:opencosmo:service-account; the task-manager profile additionally needs urn:opencosmo:service-account:task-manager in the backend's AUTH_ADMINS.

Releasing

Run the Release workflow in GitHub Actions with component=cli (or all for a major bump); the resulting cli-v* tag triggers publish-cli.yml, which tests, verifies the tag matches pyproject.toml, and publishes to PyPI via trusted publishing. No manual tagging.