# CLI

Every parity command and flag.

{/* Generated by scripts/reference.mjs from generated/*.json. Do not edit. */}

`parity` is a single static binary. Commands that talk to Parity read `PARITY_API` (set it to `https://api.parity.ninja`; there is no default) and `PARITY_TOKEN`, print JSON on stdout and progress on stderr, and exit non-zero on failure. Commands that take a sandbox default to the one named after your git branch; `--sandbox` picks another.

## `parity approve` [#parity-approve]

Approve a block step that waits: a release's, or a rollout's in an environment.

```sh
parity approve <step> [--release N | --env <environment>]
```

approve decides a block step. Without `--env`, a block of a release (release.steps):
the newest release waiting at that step, or `--release` N. With `--env`, a block
job of the environment's current rollout (jobs: with block:). It prints the
step's prompt and asks you to confirm, unless `--yes`. Approve lets the steps
after it run; reject ends the release (or fails the rollout). Only people
decide: a sandbox token or an agent can't.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--env` | string |  | A rollout's block job in this environment, such as production. |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--message`, `-m` | string |  | A note kept with the decision. |
| `--project` | string |  | Project (default: the manifest's) |
| `--release` | int64 |  | The release number (default: the newest waiting at that step) |
| `--yes`, `-y` |  |  | Don't ask to confirm. |

## `parity auth` [#parity-auth]

Manage the users of a sandbox's auth resource and mint sign-in links.

### `parity auth user` [#parity-auth-user]

Create, list, update and delete users.

### `parity auth user create` [#parity-auth-user-create]

Create a user (email verified, no MFA); prints \{id, email, password, orgs\}.

```sh
parity auth user create <email>
```

Create a user. The email is verified and there is no MFA. Without
`--password`, one is generated and printed once.

Give memberships as pairs: `--org` acme `--role` admin `--org` beta `--role` viewer.
An `--org` without its `--role` gets the role "member".

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--org` | string |  | Org slug (repeatable) |
| `--password` | string |  | Password (default: generated) |
| `--role` | string |  | Role in the --org just before it (default member) |

### `parity auth user delete` [#parity-auth-user-delete]

Delete a user and revoke its tokens.

```sh
parity auth user delete <email|id>
```

### `parity auth user get` [#parity-auth-user-get]

Show one user.

```sh
parity auth user get <email|id>
```

### `parity auth user list` [#parity-auth-user-list]

List users.

```sh
parity auth user list
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--limit` | number |  | Users per page (default 50, at most 500) |
| `--page-token` | string |  | The page after a previous list (its next_page_token) |
| `--q` | string |  | Only users whose email contains this. |

### `parity auth user update` [#parity-auth-user-update]

Change a user's email, password or memberships.

```sh
parity auth user update <email|id>
```

Change a user. Only the flags given change. `--org` and `--role` replace the
whole membership list; `--no-orgs` clears it. `--password` "" generates a new
password and prints it.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--email` | string |  | New email. |
| `--no-orgs` |  |  | Remove every membership. |
| `--org` | string |  | Org slug (repeatable; replaces all memberships) |
| `--password` | string |  | New password (empty: generated) |
| `--role` | string |  | Role in the --org just before it (default member) |

## `parity check` [#parity-check]

Check parity.yaml and show what each service gets (no cluster needed)

```sh
parity check
```

check reads parity.yaml, reports every problem it finds at once, and prints
what the platform will run: each service's image, port and public URL, every
env variable with where its value comes from (including the PORT and the
standard variables that depends_on adds), and when each job runs. It needs no
cluster and no images. It exits 1 when the manifest has a problem.

With `--env` staging or `--env` production, it prints what that environment runs:
the base with environments.&lt;name&gt; merged in, each value the environment sets
marked (environments.&lt;name&gt;).

A manifest may include other files (include:). check then cites every
problem as file:line, names the file each entry comes from, and warns about
each parity.yaml or *.parity.yaml under the root's directory that nothing
includes. `--merged` prints the one merged manifest that parity up and promote send,
each entry marked with the file and line it comes from.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--env` | string |  | Show what an environment runs: staging or production. |
| `--json` |  |  | Print the report as JSON. |
| `--manifest`, `-f` | string | `parity.yaml` | Path to the manifest. |
| `--merged` |  |  | Print the merged manifest (one file, with each entry's source) that parity up and promote send. |

## `parity down` [#parity-down]

Delete a sandbox and everything in it.

```sh
parity down
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--timeout` | duration | `5m0s` | Give up waiting after this long. |
| `--wait` |  | `true` | Wait until everything is gone. |

## `parity environments` [#parity-environments]

List the project's environments, or show one with its steps.

```sh
parity environments [environment]
```

environments lists the environments the project's manifest declares: where
each takes its builds from, whether it is frozen, its current rollout and
status, and the block steps waiting for a person, with their prompts. With an
environment, it shows that one in full (services, steps, conditions).

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--project` | string |  | Project (default: the manifest's) |

## `parity exec` [#parity-exec]

Run a command in a service or resource and print its output.

```sh
parity exec <service> -- <command>...
```

exec runs a command in a running container of a service or resource (such
as psql in db) and prints its stdout and stderr; parity exits with the
command's exit code. `--json` prints \{exit_code, stdout, stderr\} instead.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--json` |  |  | Print the result as JSON. |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--stdin` | string |  | Text to send on the command's stdin. |
| `--timeout` | string |  | Give up after this long (default 60s, at most 10m) |

## `parity freeze` [#parity-freeze]

Hold deploys to an environment, with a note; no argument lists the freezes.

```sh
parity freeze [staging|production]
```

freeze holds deploys to staging or production until someone runs parity
unfreeze or the freeze reaches `--for` or `--until`. A deploy it stops (parity
promote, the console's Promote) fails with the note, who set it and when.
Rollback is never frozen. Freezing again replaces the note.

With no environment, freeze prints the project's freezes. Setting and
lifting needs a project token with environments.deploy; a sandbox token can
read them but not change them.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--for` | duration |  | Lift by itself after this long (2h, 72h) |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--message`, `-m` | string |  | Why deploys are held. |
| `--project` | string |  | Project (default: the manifest's) |
| `--until` | string |  | Lift by itself at this time (RFC 3339) |

## `parity import` [#parity-import]

Start a parity.yaml from another app format.

### `parity import score` [#parity-import-score]

Write a parity.yaml from Score workload files (score.dev/v1b1)

```sh
parity import score [file or dir]...
```

&#105;mport score reads Score workload files (one workload per file; a directory
means every score*.yaml under it) and writes a parity.yaml: each workload is a
service, postgres, redis and s3 resources are managed entries, route is
expose, and $\{resources.&lt;r&gt;.&lt;output&gt;\} placeholders become $\{&lt;entry&gt;.&lt;attr&gt;\}.
What it can't map is printed on stderr, then the result is checked as
parity check would. Without `--out` it prints the manifest on stdout.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--force` |  |  | Overwrite --out if it exists. |
| `--out`, `-o` | string |  | Write the manifest to this file instead of stdout. |
| `--project` | string |  | Project name (default: the directory's name) |

## `parity inbox` [#parity-inbox]

Read the sandbox's email.

### `parity inbox attachment` [#parity-inbox-attachment]

List a message's attachments, or download one (-o file, - for stdout)

```sh
parity inbox attachment <msg> [part-or-name]
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--output`, `-o` | string |  | File to write (default: the attachment's name; - for stdout) |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |

### `parity inbox list` [#parity-inbox-list]

List messages, newest first, with their links, codes and attachments.

```sh
parity inbox list
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--after` | string |  | Only messages received after this message id (or now, start) |
| `--limit` | number |  | At most this many messages (default 50) |
| `--page-token` | string |  | The page after a previous list (its next_page_token) |
| `--q` | string |  | Search every message, not one page (Mailpit's search: words, to:, subject:); not with --after. |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--since` | string |  | Only messages newer than this: a duration such as 5m, or an RFC 3339 time. |
| `--subject` | string |  | Text the subject contains, in any case. |
| `--subject-re` | string |  | Regular expression the subject matches (RE2; (?i) for any case) |
| `--to` | string |  | Recipient: an address, or a name alone (bob) for bob@ at any domain. |

### `parity inbox read` [#parity-inbox-read]

Read one message: text, links, codes, attachments (--html for the HTML part)

```sh
parity inbox read <msg>
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--html` |  |  | Also print the HTML part. |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |

### `parity inbox wait` [#parity-inbox-wait]

Wait for a message and print it (--none: assert that none arrives)

```sh
parity inbox wait
```

wait prints the first message that matches, as soon as there is one.

Without `--after` it is the newest match, which may have arrived before the
wait. With `--after` &lt;id|now&gt; it is the oldest match received after that
message: chain waits with `--after` set to the last message's id to see each
message once.

`--none` asserts the opposite: that no match arrives after the cursor (default
now) for `--timeout`. It prints \{"none": true, ...\} with the window and exits
0, or prints the message that came and exits 1. The calls are in
calls.jsonl, so the proof holds the negative evidence.

Each API call waits at most about 50 s; parity calls again, after Retry-After,
until `--timeout`.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--after` | string |  | Only a message received after this message id, or now (default: any message; --none: now) |
| `--html` |  |  | Also print the HTML part. |
| `--none` |  |  | Assert that no matching message arrives within --timeout. |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--since` | string |  | Only messages newer than this: a duration such as 5m, or an RFC 3339 time. |
| `--subject` | string |  | Text the subject contains, in any case. |
| `--subject-re` | string |  | Regular expression the subject matches (RE2; (?i) for any case) |
| `--timeout` | duration | `1m0s` | How long to wait. |
| `--to` | string |  | Recipient: an address, or a name alone (bob) for bob@ at any domain. |

## `parity logs` [#parity-logs]

Print logs of a service, a job, or the whole sandbox.

```sh
parity logs [service|job]
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--since` | string |  | Only logs newer than this duration, such as 10m. |
| `--tail` | number |  | Lines per container (default 200, or 100 with no service or job; at most 10000) |
| `--timestamps` |  |  | Prefix each line with its time. |

## `parity mcp` [#parity-mcp]

Serve the Parity MCP tools on stdin and stdout, for a local agent (needs PARITY_API and PARITY_TOKEN)

```sh
parity mcp
```

mcp serves the sandbox tools (sandbox_status, auth_user_create, inbox_wait,
job_run, sandbox_logs, sandbox_exec, proof_add, proof_export, ...) over MCP's
stdio transport. Every call goes to Parity's API at PARITY_API with PARITY_TOKEN,
so the agent can do exactly what its token allows. Register it with an agent,
for example: claude mcp add parity `-e` PARITY_API=... `-e` PARITY_TOKEN=pst_... -- parity mcp

## `parity open` [#parity-open]

Print the app's URL (with --browser, open it)

```sh
parity open
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--browser`, `-b` |  |  | Open the URL in a browser. |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--service` | string |  | The service whose URL to open (default: the first with one) |

## `parity promote` [#parity-promote]

Make this manifest the project's current one, which staging and production follow.

```sh
parity promote [environment]
```

promote makes this parity.yaml the project's current manifest, which
staging and production will follow, and keeps it as a revision. Sandboxes
don't follow it: each pins the manifest it was created from, so promoting
never changes a running sandbox. Prints \{project, generation, revision\}.
It needs a project token; a sandbox token can't promote. While production is
frozen (parity freeze) it is refused with the freeze's note.

With an environment, promote ships a release's build into it by hand, outside
the release's steps: the newest release, or `--release` N. It is how a hotfix
skips a step, and how an environment a rollback pinned is unpinned. It asks
you to confirm, unless `--yes`.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--manifest`, `-f` | string | `parity.yaml` | Path to the manifest. |
| `--project` | string |  | Project, with an environment (default: the manifest's) |
| `--release` | int64 |  | With an environment: the release whose build to ship (default: the newest) |
| `--yes`, `-y` |  |  | Don't ask to confirm. |

## `parity proof` [#parity-proof]

Attach evidence to the sandbox's proof bundle, and export it (needs PARITY_API)

### `parity proof add` [#parity-proof-add]

Attach files (screenshots, test output) with a note, in one call.

```sh
parity proof add <file|dir>...
```

add attaches files to the proof bundle, in one call: each file, and the files
directly in each directory given (not hidden ones, not subdirectories). The
note is every file's note. Parity records each file's content type, from its
extension or its first bytes.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--name` | string |  | Name in the bundle, for a single file (default: the file's name) |
| `--note` | string |  | What the file shows. |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |

### `parity proof export` [#parity-proof-export]

Export the proof bundle as a zip.

```sh
parity proof export
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--claim` | string |  | What the change does (proof.json verdict.claim) |
| `--output`, `-o` | string |  | Zip to write (default proof-&lt;id&gt;.zip) |
| `--result` | string |  | Your verdict, such as pass (proof.json verdict.result) |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--summary` | string |  | What a reviewer should read first (proof.json verdict.summary) |

### `parity proof verify` [#parity-proof-verify]

Check that a proof bundle was signed by Parity and not changed since.

```sh
parity proof verify <proof.zip>
```

verify checks signature.json: the ed25519 signature over the manifest of every
file in the zip, then each file's size and SHA-256. Any edited, added or
removed file fails it.

Offline, pass the public key with `--key` (a file or text holding the JSON of
GET /v0/keys, or one base64 key). Online, with PARITY_API set, the keys come
from Parity's GET /v0/keys, and with PARITY_TOKEN too, Parity is asked whether it
holds this very bundle. parity exits 1 when the bundle fails.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--key` | string |  | The public key, for offline checks: a file or text with GET /v0/keys's JSON, or one base64 ed25519 key. |

## `parity reject` [#parity-reject]

Reject a block step that waits: a release's, or a rollout's in an environment.

```sh
parity reject <step> [--release N | --env <environment>]
```

reject decides a block step. Without `--env`, a block of a release (release.steps):
the newest release waiting at that step, or `--release` N. With `--env`, a block
job of the environment's current rollout (jobs: with block:). It prints the
step's prompt and asks you to confirm, unless `--yes`. Approve lets the steps
after it run; reject ends the release (or fails the rollout). Only people
decide: a sandbox token or an agent can't.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--env` | string |  | A rollout's block job in this environment, such as production. |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--message`, `-m` | string |  | A note kept with the decision. |
| `--project` | string |  | Project (default: the manifest's) |
| `--release` | int64 |  | The release number (default: the newest waiting at that step) |
| `--yes`, `-y` |  |  | Don't ask to confirm. |

## `parity releases` [#parity-releases]

List the project's releases, or show one with its steps.

```sh
parity releases [number]
```

releases lists the project's releases, newest first: each is one build moving
through the manifest's release steps (promote, block, wait, run, group), with
where it is and what it waits for. With a number, it shows that release's
steps in full: each promote's environments, each block's prompt and
decisions, each wait's end.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--limit` | number | `20` | How many releases to list (at most 30) |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--project` | string |  | Project (default: the manifest's) |

## `parity render` [#parity-render]

Print a sandbox's Kubernetes objects as multi-document YAML, by phase.

```sh
parity render
```

render prints the Kubernetes objects Parity would apply for one sandbox, in
three phases, each introduced by a "# phase: N" comment:

  1  namespace, network policy, secrets and managed services
  2  deploy jobs, then seed jobs, then start jobs, in order
  3  services and public routes

Nothing is applied. Generated values are kept in `--seed-file` when given, so
re-renders keep them. With `--env` staging or `--env` production, it prints what
that environment would run.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--env` | string |  | Render what a declared environment runs, such as production. |
| `--image` | string, repeatable |  | Image for a service, as service=ref (repeatable; required for build-only services, and shared by services with the same build block) |
| `--manifest`, `-f` | string | `parity.yaml` | Path to the manifest. |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--seed-file` | string |  | YAML file of generated values; read if present, then updated. |

## `parity retry` [#parity-retry]

Roll out an environment's current build again (after a failure, reject or timeout)

```sh
parity retry <environment>
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--project` | string |  | Project (default: the manifest's) |
| `--yes`, `-y` |  |  | Don't ask to confirm. |

## `parity rollback` [#parity-rollback]

Roll an environment back to a build it ran before.

```sh
parity rollback <environment>
```

rollback makes the environment run one of its last 5 builds again: the
previous one, or `--to` a commit or App revision. Its block steps pass (the
build passed them before), and it is never frozen. A branch environment stays
there, pinned, until someone promotes it: releases hold their promotes into it
meanwhile. It asks to confirm, unless `--yes`.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--project` | string |  | Project (default: the manifest's) |
| `--to` | string |  | A commit or App revision the environment ran recently. |
| `--yes`, `-y` |  |  | Don't ask to confirm. |

## `parity run` [#parity-run]

Run a manifest job now and wait for it.

```sh
parity run <job>
```

run starts one of the manifest's jobs now, from the manifest revision the
sandbox pins, waits for it, and prints its status and log tail. This is how
a schedule fires in a sandbox, where its CronJob is suspended.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |

## `parity sandbox` [#parity-sandbox]

Inspect, list and extend sandboxes.

### `parity sandbox extend` [#parity-sandbox-extend]

Push a sandbox's expiry back, up to max_ttl.

```sh
parity sandbox extend <duration>
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |

### `parity sandbox list` [#parity-sandbox-list]

List sandboxes.

```sh
parity sandbox list
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--limit` | number |  | Sandboxes per page (default 50, at most 500) |
| `--page-token` | string |  | The page after a previous list. |

### `parity sandbox status` [#parity-sandbox-status]

Print a sandbox's status as JSON.

```sh
parity sandbox status
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |

## `parity scale` [#parity-scale]

Set how many replicas a service runs in the sandbox (0 stops it)

```sh
parity scale <service> <replicas>
```

scale sets a service's replica count in the sandbox: 0 stops it, 1 is the
manifest's default. It lasts for the sandbox's life and is not a rollout, so
deploy jobs don't rerun. Use it to quiet a service whose process runs its
own schedule (Plane's beat, say): the manifest's own \{ schedule \} jobs are
already suspended in sandboxes, and parity run &lt;job&gt; fires one.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |

## `parity signin` [#parity-signin]

Mint a one-time sign-in link; prints \{url, expires_at\}.

```sh
parity signin <email|id>
```

Mint a one-time sign-in link for a user. Opening it in a browser signs the
user in at the auth resource and starts the app's own OIDC login (its
initiate_login_uri), so the app's callback runs and the app sets its own
session. The link works once and expires after 15 minutes.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--org` | string |  | Org the tokens carry in org and roles (default: the user's first org) |
| `--redirect` | string |  | Where the browser should end up (sent to the app as target_link_uri) |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |

## `parity skip` [#parity-skip]

Skip a step of a release (a block, a wait, a held promote), saying why.

```sh
parity skip <step> -m <reason> [--release N]
```

skip passes over a step of a release that hasn't finished: a block nobody will
approve, a soak you don't need, a promote held by a freeze. The reason is
kept in the release's record. A promote whose rollouts started can't be
skipped: they finish. Without `--release`, the newest release at that step.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--message`, `-m` | string |  | Why (required) |
| `--project` | string |  | Project (default: the manifest's) |
| `--release` | int64 |  | The release number (default: the newest at that step) |
| `--yes`, `-y` |  |  | Don't ask to confirm. |

## `parity ui` [#parity-ui]

Open the web console in your browser.

```sh
parity ui
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--print` |  |  | Print the sign-in link instead of opening a browser. |

## `parity unfreeze` [#parity-unfreeze]

Lift an environment's deploy freeze.

```sh
parity unfreeze <staging|production>
```

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--manifest`, `-f` | string | `parity.yaml` | Manifest whose project to use. |
| `--project` | string |  | Project (default: the manifest's) |

## `parity up` [#parity-up]

Create a sandbox, or bring an existing one up to date, and wait until it is ready.

```sh
parity up
```

up creates a sandbox from parity.yaml, or brings an existing one up to
date, and waits until it is ready: managed services up, deploy, seed and
start jobs done, services healthy. While it waits it prints what the
sandbox is waiting for, such as an image being pulled or a job running.
It stops early with the reason when something needs a change from you,
such as an image that can't be pulled or a job that failed.

Rerunning it is safe: the sandbox keeps its generated values, its creation
time and its token, a changed manifest rolls out, and a failed sandbox
retries what failed. A job whose container never started is replaced by
the new manifest's job.

In a git checkout the sandbox is named after the branch (feature/orders
runs as feature-orders), and `--ref` and `--commit` default to the branch and
HEAD. With a sandbox token, up updates that token's own sandbox.

While it waits, it prints each outbound call the sandbox blocked (a host
missing from externals). When something is stuck: parity sandbox status
shows each service's and job's state and reason and the blocked hosts
(egress.blocked), and parity logs &lt;service or job&gt; shows its log, or why it
has none yet.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--agent` | string |  | The agent acting for you, such as "Claude Code" (default $PARITY_AGENT) |
| `--build` |  |  | Ignore develop.watch sync rules and build every service's real image, as staging and production run it. |
| `--commit` | string |  | Git commit the sandbox runs. |
| `--dev` | list |  | Run these services in dev mode: their develop.command, fed by their develop.watch sync rules (repeatable or comma-separated; each up states the full list) |
| `--idempotency-key` | string |  | Sent as Idempotency-Key, so rerunning with the same key returns the same sandbox and token. |
| `--image` | string, repeatable |  | Image for a service, as service=ref (repeatable); it also goes to every service with the same build block. |
| `--manifest`, `-f` | string | `parity.yaml` | Path to the manifest. |
| `--pr` | string |  | Its pull request: a number or a URL. |
| `--ref` | string |  | Git ref (branch) the sandbox runs. |
| `--sandbox` | string |  | Sandbox ID (default $PARITY_SANDBOX, the sandbox token's, or the git branch) |
| `--task` | string |  | The task it is for: a title, optionally followed by a URL. |
| `--timeout` | duration | `15m0s` | Give up waiting after this long. |
| `--ttl` | string |  | Lifetime from creation (default: the manifest's sandbox.ttl, else 2h) |
| `--wait` |  | `true` | Wait until the sandbox is ready. |