---
title: "Commands | Parity docs"
description: "Every parity command and option, from the program's own help, with exit codes and the environment variables it reads."
url: https://parity.apps.wayne.edu/docs/reference/commands.html
llms: https://parity.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# Commands [#](https://parity.apps.wayne.edu/docs/reference/commands.html#commands)

Every command, with the options its own `--help` prints. Run `parity <command> --help` for the same text in your terminal. Options take one dash or two (`-json` and `--json` are the same).

```text
Usage: parity [-C folder] <command> [options] [--plain]
```

| Command | What it does |
| --- | --- |
| `parity check` | tells you what to fix before Parity can run Citadel here, one finding per line |
| `parity init` | writes `parity.json`, the app's Citadel settings (`--from-squire` reads a Squire kit) |
| `parity up` | runs the app the way Citadel runs it, on Citadel's own image, behind the proxy |
| `parity status` | shows how the app, MySQL and the proxy are doing |
| `parity image` | lists, gets or verifies Citadel's images (`get` downloads one and checks it is Citadel's) |
| `parity logs` | shows the app's output (`-f` follows; `--apache` shows Apache's own logs; `deployments` shows the deployment scripts' logs) |
| `parity test` | smoke tests the running app through the proxy (plus the requests in `parity.json`) |
| `parity trust` | puts the app's local https certificate authority in this computer's certificate stores (`--remove` takes it out again) |
| `parity run` | runs a tool in the app container as user citadel (`composer ci`, `php artisan test`, `npm run build`) |
| `parity shell` | opens a shell in the app container |
| `parity down` | stops the app (the database stays; `--volumes` empties it) |
| `parity engine` | shows or saves which container engine Parity uses (`podman`, `docker` or `auto`) |
| `parity version` | prints Parity's version |

## Global options [#](https://parity.apps.wayne.edu/docs/reference/commands.html#global-options)

| Option | What it does |
| --- | --- |
| `-C folder` | run as if started in that folder (the app's folder) |
| `--plain` | plain output: `[ OK ]`, `[WARN]`, `[FAIL]` tags, no color, no spinners. Anywhere on the line |

## Exit codes [#](https://parity.apps.wayne.edu/docs/reference/commands.html#exit-codes)

The same as PROCTOR's and Squire's, on every command:

| Code | Meaning |
| --- | --- |
| `0` | pass |
| `1` | findings, or a failed build, deployment, health check or test |
| `2` | cannot run: a usage mistake, no engine, no `parity.json`, no image, a port taken |

`--json` on the read commands (`check`, `status`, `test`, `image list`, `engine`, `version`) is the stable contract for scripts and CI. The human output may change between releases; the JSON keeps its keys.

## parity check [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-check)

```text
Usage: parity check [--json]
```

| Option | What it does |
| --- | --- |
| `--json` | print JSON (the stable contract) |

Checks the container engine (Podman, machine or native, rootless or rootful; Docker Desktop; anything that answers the `docker` command) and names any other engine that is here, Docker Compose v2 (and, on Linux, Podman's API socket), Linux containers, WSL 2 (Windows), amd64 emulation (arm64), Windows line endings in the files Citadel runs, and, with a `parity.json`, the file itself, its configuration files' required keys (by name, never values), Citadel's image and the ports. Changes nothing. With a `parity.json` and a running engine it ends with the mirror, the same rows as `parity status`.

With the app running, it also asks the app itself, one finding per line (these run only while the app is up; with the app stopped it says so and skips them):

- `app.key` (Laravel apps): `APP_KEY` is set in the local `.env` (its value is never printed).
- `app.writable`: every folder in `writable` is in the app and writable by Apache.
- `app.database`: the app can sign in to its MySQL.
- `app.migrations` (Laravel apps with MySQL): no migrations are pending.

Every command that talks to the engine uses `PARITY_ENGINE` when it is set (`podman`, `docker` or `auto`), else the choice saved with [`parity engine`](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-engine), else `auto`: the engine that is running, Docker first when both are.

## parity init [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-init)

```text
Usage: parity init [options]
```

| Option | What it does | Default |
| --- | --- | --- |
| `--force` | overwrite an existing `parity.json` |  |
| `--from-squire` | read the app's Squire parity kit (settings by name; never passwords) |  |
| `--health-check string` | Citadel's health check: a command run in the app container (`php health.php`), or a path such as `/up` that Apache must answer | guessed: `health.php`, `health-check`, or a Laravel app's health route |
| `--image string` | Citadel base image | `citadel/php-apache:8.5r3` |
| `--mode string` | `mount` (your folder is mounted, for developers) or `bake` (code copied in, for testers) | `mount` |
| `--mysql` | add MySQL 5.6 (Citadel's "MySQL: yes") |  |
| `--no-mysql` | no MySQL |  |
| `--name string` | app name (names the containers) | the folder's name |
| `--no-cron` | leave out the Laravel scheduler's cron entry even when the app schedules something |  |
| `--port int` | local HTTP port for the proxy | `8080` |
| `--print` | print the `parity.json` instead of writing it |  |
| `--public-dir string` | public folder, relative to the app (Citadel's "public directory") | `public` when there is one |
| `--sign-in string` | `none`, `fake` (SESAME's fake driver) or `cas` | `none` |

## parity up [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-up)

```text
Usage: parity up [--verbose] [--wait 5m]
```

| Option | What it does | Default |
| --- | --- | --- |
| `--verbose` | also show the build and compose output (it is always in `.parity/up.log`) |  |
| `--wait duration` | how long to wait for the app's health check | `5m0s` |

Exit 1 when the app's own build, deployments or health check failed; 2 when Parity could not run it. An image that is not on this computer is exit 2: the hint is `parity image get`, or, when Citadel has not published a download for it yet, a line that says so ([Citadel's images](https://parity.apps.wayne.edu/docs/guides/images.html#when-citadel-has-not-published-an-image-yet)). Before it starts the app, the MySQL step signs in as the app does; a database volume made with other passwords, or for another database name, stops it there with exit 2 and the way out ([Troubleshooting](https://parity.apps.wayne.edu/docs/troubleshooting.html#mysql-refuses-the-app-s-password)).

## parity status [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-status)

```text
Usage: parity status [--json]
```

| Option | What it does |
| --- | --- |
| `--json` | print JSON (the stable contract) |

Shows each piece and its health, then the mirror: your machine and Citadel side by side, one row each for the image, the image id, PHP, the platform, `php.ini`, MySQL, Node and the PHP extensions, marked match, close or differs.

```text
  Your machine and Citadel  citadel/php-apache:8.5r3
                          YOUR MACHINE                 CITADEL
  ✓ Image            citadel/php-apache:8.5r3     citadel/php-apache:8.5r3     match
  ✓ Image id         sha256:950dcf67937a          sha256:950dcf67937a          match
  ✓ PHP              8.5.12                       8.5.12                       match
  ✓ Platform         linux/amd64                  linux/amd64                  match
  ✓ php.ini          Citadel's php8.ini           Citadel's php8.ini           match
  ✓ MySQL            5.6.51                       5.6.51                       match
  ✓ Node             22.23.4                      22.23.4                      match
  ✓ PHP extensions   50 loaded                    50 loaded                    match
    Node and PHP extensions read from the running app container.

  Matches Citadel.
```

Node and the extensions come from the running app container, or else the app's image, or else Citadel's image on this computer, asked once per image id. Node is close when only the minor or patch differs and differs across a major. A missing extension differs and an extra one is close; each is listed under the extension row. The `--json` output does not change.

Exit 0 when every piece runs and is healthy, 1 when not.

## parity image [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-image)

```text
Usage: parity image list [--json]
       parity image get [tag] [--file x.tar] [--git] [--https] [--keep] [--force]
       parity image verify [tag] [--file x.tar]
```

The tag defaults to the image in `parity.json`, or Parity's newest Citadel image. [Citadel's images](https://parity.apps.wayne.edu/docs/guides/images.html) explains the download routes and what "matches Citadel" checks.

### parity image list [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-image-list)

| Option | What it does |
| --- | --- |
| `--json` | print JSON (the stable contract) |

### parity image get [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-image-get)

| Option | What it does |
| --- | --- |
| `--file string` | use a tar you downloaded yourself (from the project's page in your browser) |
| `--force` | load it again even when the image here already matches |
| `--git` | download with git LFS over SSH with your own key, even when `PARITY_GITLAB_TOKEN` is set (without a token, git is the way) |
| `--https` | with `--git`, clone over HTTPS (your git credential manager signs in) instead of SSH |
| `--keep` | keep the downloaded tar in Parity's cache folder |

### parity image verify [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-image-verify)

| Option | What it does |
| --- | --- |
| `--file string` | check a downloaded tar's sha256 instead of the loaded image |

Exit 1 when the image (or tar) differs from Citadel's.

## parity logs [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-logs)

```text
Usage: parity logs [app|mysql|proxy|cron:<name>|deployments[:<file>]] [-f] [--tail 100] [--apache]
```

| Option | What it does | Default |
| --- | --- | --- |
| `--apache` | Apache's error and access logs from `/citadel/logs/apache` (where Citadel keeps them) |  |
| `-f` | keep following (Ctrl+C stops) |  |
| `--tail int` | how many lines to start with | `100` |

`cron:<name>` shows one [cron entry](https://parity.apps.wayne.edu/docs/reference/parity-json.html#cron-entries)'s stdout and stderr files from `/citadel/logs/cron-jobs`, as Citadel's dashboard does. `parity logs app` shows each run as it happens: `cron:<name> >` the command started, `|` a line of its output, `!` a line of its errors, `<` how it ended.

`deployments` shows the deployment scripts' own logs from `/citadel/logs/deployments`: the newest `*.failed.log`, else the newest `*.log`; `deployments:<file>` shows that file. They are read through the app container, so they show while the app is stopped after a failed deployment, which is also why `parity up` ends with the failed deployment's own log.

## parity test [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-test)

```text
Usage: parity test [--json]
```

| Option | What it does |
| --- | --- |
| `--json` | print JSON (the stable contract) |

Requests the front page through the proxy, runs the app's health check, makes the requests in `test.requests`, and fails on a PHP fatal or parse error in Apache's log while it ran. A request passes on any answer below 500 unless it names a `status`, and must contain `contains` when it names one. Redirects are not followed. When the engine's own connection drops before a check reaches the container (Podman on Windows, now and then), that check is tried once more; see [Podman lost its connection](https://parity.apps.wayne.edu/docs/troubleshooting.html#podman-lost-its-connection).

## parity trust [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-trust)

```text
Usage: parity trust [--remove]
```

| Option | What it does |
| --- | --- |
| `--remove` | take the CA out of your user store again |

Puts the app's local https certificate authority in this computer's certificate stores, so the browser stops warning about the app's https address on 127.0.0.1:8443. The CA lives in Parity's per-user config folder (`ca/<app>`); only `ca.crt` goes anywhere, and the CA key never leaves that folder. Per operating system:

- **Windows:** adds the CA to your user's Root store with `certutil -user` (no administrator needed); `--remove` deletes it by thumbprint.
- **macOS:** adds it to your login keychain with `security add-trusted-cert -r trustRoot`; `--remove` deletes it by thumbprint.
- **Linux:** the system store needs sudo, which Parity will not ask for, so it prints the two commands for you to run: `sudo cp` into `/usr/local/share/ca-certificates/` plus `sudo update-ca-certificates` (Debian and Ubuntu), or into `/etc/pki/ca-trust/source/anchors/` plus `sudo update-ca-trust extract` (Fedora and RHEL). When `certutil` is on your PATH and `~/.pki/nssdb` exists, Parity also updates that NSS database itself, because Chrome and Chromium read it. Firefox keeps its own store, so Parity prints the manual step: import `ca.crt` under Settings, Certificates, Authorities.

Exit 0 when the store changed (or was printed, on Linux), 2 when it could not run: no `parity.json`, `"https"` off in it, a CA problem (for example `server_name` changed since the CA was made; delete the app's CA folder in Parity's config dir, then `parity up` again and `parity trust` once it exists), or a certificate-store command that failed.

## parity run [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-run)

```text
Usage: parity run [--user citadel] [--] command [args...]
```

| Option | What it does | Default |
| --- | --- | --- |
| `--user string` | run as this user: `citadel` owns the code, so files the tool writes belong to it (root is `--user root`) | `citadel` |

Runs one tool in the app container, in `/citadel/src`, the same container `parity up` runs: `composer ci`, `php artisan test`, `npm run build`, instead of a raw `docker run` line. Only flags before the command are Parity's (a leading `--` is accepted and dropped); everything after goes to the tool. The exit code is the command's own.

In bake mode Parity says the files the command writes live in the container and vanish on the next `parity up`; in mount mode they land in your folder.

## parity shell [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-shell)

```text
Usage: parity shell [--user citadel] [command...]
```

| Option | What it does | Default |
| --- | --- | --- |
| `--user string` | run as this user: `citadel` owns the code, `prisoner` runs Apache | `root`, as Citadel's build does |

Opens in `/citadel/src`. With a command, runs just that command and exits with its code.

## parity down [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-down)

```text
Usage: parity down [--volumes]
```

| Option | What it does |
| --- | --- |
| `--volumes` | also empty the local database and logs (fake data only, but it is gone) |

## parity engine [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-engine)

```text
Usage: parity engine [podman|docker|auto] [--json]
```

| Option | What it does |
| --- | --- |
| `--json` | print JSON (the stable contract) |

With no choice, says which engine Parity uses and why: `PARITY_ENGINE`, the saved choice, or the engine that answers. With one, saves it for you on this computer, not for the app, so every app and the desktop app's Settings use it too (they read and write the same `parity/settings.json` in your config folder; `PARITY_APP_CONFIG_DIR` moves it). `auto` clears the choice. `PARITY_ENGINE` still wins where it is set, and the command says so. Anything but `podman`, `docker` or `auto` is exit 2, and nothing is written.

## parity version [#](https://parity.apps.wayne.edu/docs/reference/commands.html#parity-version)

```text
Usage: parity version [--json]
```

| Option | What it does |
| --- | --- |
| `--json` | print JSON (the stable contract) |

Prints the version, the commit it was built from, the Go version and the OS and architecture.

## Environment variables [#](https://parity.apps.wayne.edu/docs/reference/commands.html#environment-variables)

| Variable | What it does |
| --- | --- |
| `PARITY_GITLAB_TOKEN` | a git.wayne.edu personal access token (`read_repository` is enough) for `parity image get`. Read from the environment only, never printed |
| `PARITY_PLAIN` | `1` is the same as `--plain` |
| `PARITY_STYLE` | `fancy` keeps symbols and color even in a pipe or a log |
| `NO_COLOR` | any value turns color off and keeps the symbols |
