git:20260315.85ba619 to git:20261013.6baa667

11 added, 0 removed. Audit A to A.

---

name: magnus

description: Run blueprints on the Magnus cloud platform via the `magnus` CLI. Use this skill when you need to execute remote computations on GPU/CPU clusters.

---

# Magnus CLI

Magnus executes **blueprints** on remote GPU/CPU clusters. The CLI is self-documenting — use `--help` at each level to discover what's available:

```bash

magnus --help # top-level commands and shortcuts

magnus run --help # CLI options for blueprint execution

magnus job --help # job inspection and management

magnus blueprint schema <blueprint-id> # parameter schema for a specific blueprint

```

## Setup

```bash

pip install "magnus-sdk>=0.6.0"

magnus config # check current connection — skip setup if already configured

```

If not configured, run `magnus login` (saves to `~/.magnus/config.json`, all shells pick up immediately):

```bash

magnus login # interactive

magnus login <site> -a <address> -t <token> # non-interactive (for scripts and agents)

```

#### Config resolution order

| Priority | Source | Use case |

|----------|--------|----------|

| 1 (highest) | Environment variables `MAGNUS_ADDRESS`, `MAGNUS_TOKEN` | CI/CD pipelines, automation scripts |

| 2 | `~/.magnus/config.json` (via `magnus login`) | **Recommended for interactive use** |

| 3 (lowest) | Built-in default site | Fallback |

**Do not use environment variables for interactive work.** Inline `MAGNUS_ADDRESS=... magnus run ...` is non-portable and not persisted. If `magnus config` shows an env-override warning, remove the `export` lines from your shell profile (`.bashrc`, `.zshrc`, or system environment variables on Windows) to let `magnus login` take effect.

## Core Workflow

Run `magnus config` first to verify your connection. If not configured, use `magnus login` once — credentials persist across all shells and subsequent commands. Do not inline `MAGNUS_ADDRESS`/`MAGNUS_TOKEN` environment variables before each command.

```

magnus list # discover available blueprints

magnus blueprint schema <id> # inspect parameters, types, defaults

magnus run <id> [--] --key value ... # execute and wait for result

```

### The `--` separator

Divides CLI options (left) from blueprint arguments (right). **Optional** — without it, all arguments route to the blueprint and CLI options use defaults. See `magnus run --help` for available CLI options.

### FileSecret — automatic file upload

When a blueprint parameter is typed `FileSecret`, passing a local file path triggers automatic upload. Files and directories both work. Check `magnus blueprint schema <id>` to see which parameters accept file paths.

### Output download (MAGNUS_ACTION)

Blueprints that produce output files write a `magnus receive` command to `MAGNUS_ACTION`. With `--execute-action true` (default), `magnus run` auto-executes this receive command.

+ Files also have direct, supported CLI interfaces:

+ ```bash

+ magnus custody ./output --expire-minutes 120 --secret-only # stdout: magnus-secret:...

+ magnus receive <file-secret> --output ./downloaded-output

+ ```

+ The Python equivalents are `custody_file()` and `download_file()`. A runner must propagate a required-output upload failure as a nonzero exit, and obtain a nonempty secret before reporting delivery success. A successful computation or ZIP command alone does not prove delivery. On offline relay sites, custody stages outputs locally; retrieval becomes available after the controller imports them.

+ Custody is temporary: ordinary secrets have TTL/download-count limits and become invalid on backend restart. Retrieve required results promptly. HTTP transfers use single requests without resumable upload sessions; public gateways can impose smaller request-size limits than Magnus. Preserve HTTP status and request ID when reporting failures; do not expose credentials or assume a longer timeout fixes HTTP 413.

## Job Management

```bash

magnus job result <job-id> # structured result (same as magnus run output)

magnus logs <job-id> # stdout + stderr from cloud execution

magnus status <job-id> # job status

magnus kill <job-id> # terminate a running job

magnus jobs # list recent jobs with IDs

```

`<job-id>` is the absolute job ID printed by `magnus run` (e.g. `abc123`). Negative indices also work as a shorthand (`-1` = most recent, `-2` = second most recent), but they are scoped to your account, not your session — if another agent or session submits a job under the same account, the indices shift. In multi-step pipelines, prefer capturing the job ID from `magnus run` output and passing it explicitly.

Blueprint results typically contain at minimum `success` (bool) and `message` (str).

## Error Handling

If `magnus run` returns a non-success result:

1. `magnus job result <job-id>` — structured error details

2. `magnus logs <job-id>` — full execution output

3. Fix and re-run

Jobs continue server-side even if your client disconnects — interrupting `magnus run` (Ctrl-C) or a network drop only detaches the local client, the job keeps running. **Do not re-submit** — instead, reconnect:

1. `magnus status <job-id>` (or `sleep 30 && magnus status <job-id>` to wait out a transient outage)

2. Once the job shows completed, `magnus job result <job-id>` to read `MAGNUS_RESULT`

3. Run the `magnus receive` command from `MAGNUS_ACTION` to download outputs

Use `magnus kill <job-id>` to terminate a job that was submitted with wrong parameters to free up cluster resources.