Metadata-Version: 2.4
Name: opencosmo-portal
Version: 0.2.0
Summary: CLI and local MCP server for the OpenCosmo platform
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: joserfc>=1.6.1
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# OpenCosmo Portal CLI (`ocp`)

Command-line interface and local MCP server for the [OpenCosmo](../README.md) platform. Query cosmological simulation datasets at DOE Leadership Computing Facilities from your terminal.

## Installation

```bash
pip install opencosmo-portal
```

Or for development:

```bash
cd cli
uv sync
```

## Quick Start

The default profile points to `http://localhost:8000` (local development).
For development against a local backend:

```bash
# Authenticate via browser (Globus OAuth)
ocp auth login

# Browse available tasks
ocp task list
ocp task info <slug>

# Submit a task and monitor the run
ocp task run <slug>
ocp run status <run-id> --watch
ocp run results <run-id>
```

## Commands

### `ocp auth` — Authentication

| Command             | Description                             |
| ------------------- | --------------------------------------- |
| `ocp auth login`    | Authenticate via browser (Globus OAuth) |
| `ocp auth logout`   | Clear stored tokens                     |
| `ocp auth status`   | Show token status and expiry            |

### `ocp config` — Profile Management

| Command                                | Description              |
| -------------------------------------- | ------------------------ |
| `ocp config list`                      | List all profiles        |
| `ocp config add-profile <name> <url>`  | Add or update a profile  |
| `ocp config set-profile <name>`        | Set default profile      |
| `ocp config remove-profile <name>`     | Delete a profile         |
| `ocp config show [name]`               | Show profile details     |

### `ocp task` — Tasks

| Command                  | Description                                |
| ------------------------ | ------------------------------------------ |
| `ocp task list`          | List available tasks                       |
| `ocp task info <slug>`   | Show task details and input parameters     |
| `ocp task run <slug>`    | Submit a task (interactive or `--input`)   |

### `ocp run` — Runs

| Command                        | Description          |
| ------------------------------ | -------------------- |
| `ocp run list`                 | List your runs       |
| `ocp run status <id> [--watch]`| Check run status     |
| `ocp run logs <id>`            | View run logs        |
| `ocp run results <id>`         | Download results     |
| `ocp run cancel <id>`          | Cancel a run         |
| `ocp run archive <id>`         | Archive a run        |

### `ocp whoami` — User

Show current user info.

### `ocp mcp` — MCP Server

Start a local stdio MCP server for AI assistants like Claude Desktop.

```bash
ocp mcp start
```

Configure in Claude Desktop (`claude_desktop_config.json`):

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

## Global Options

| Option             | Description                                |
| ------------------ | ------------------------------------------ |
| `--profile, -p`    | Use a specific profile                     |
| `--format, -f`     | Output format: `table` (default) or `json` |
| `--version`        | Show version                               |
| `--help`           | Show help for any command                  |

## Releasing

The CLI is published to PyPI as `opencosmo-portal` via GitHub Actions (trusted publisher / OIDC).

### Automated (recommended)

Use the **Release CLI** workflow in GitHub Actions:

1. Go to **Actions → Release CLI → Run workflow**
2. Select the bump type (`patch`, `minor`, or `major`)
3. The workflow bumps `cli/pyproject.toml`, commits, tags, and pushes — which
   triggers the publish workflow automatically

### Manual

1. Bump `version` in `cli/pyproject.toml` (or run `cd cli && uv version --bump patch`)
2. Commit: `git commit -am "release: CLI v0.2.0"`
3. Tag: `git tag cli-v0.2.0`
4. Push both: `git push origin main cli-v0.2.0`

The [`publish-cli.yml`](../.github/workflows/publish-cli.yml) workflow will:
- Run the full test suite
- Verify the tag version matches `pyproject.toml`
- Build and publish to PyPI

### First-time setup

Register a [trusted publisher](https://docs.pypi.org/trusted-publishers/) on pypi.org:

| Field        | Value                  |
| ------------ | ---------------------- |
| Package name | `opencosmo-portal`     |
| Owner        | `ArgonneCPAC`          |
| Repository   | `OpenCosmoPortal`      |
| Workflow     | `publish-cli.yml`      |
| Environment  | `pypi`                 |

Then create a `pypi` environment in GitHub repo settings → Environments.

## Configuration

Config and tokens are stored in `~/.opencosmo/`:

```
~/.opencosmo/
├── config.json          # Profiles (name → API URL)
└── tokens/
    └── <profile>.json   # OAuth tokens per profile
```
