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).
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#
| 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#
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#
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_KEYis set in the local.env(its value is never printed).app.writable: every folder inwritableis 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, else auto: the engine that is running, Docker first when both
are.
parity init#
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#
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).
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).
parity status#
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.
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#
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 explains the download routes and what "matches Citadel" checks.
parity image list#
| Option | What it does |
|---|---|
--json |
print JSON (the stable contract) |
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#
| 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#
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'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#
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.
parity trust#
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);--removedeletes it by thumbprint. - macOS: adds it to your login keychain with
security add-trusted-cert -r trustRoot;--removedeletes 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 cpinto/usr/local/share/ca-certificates/plussudo update-ca-certificates(Debian and Ubuntu), or into/etc/pki/ca-trust/source/anchors/plussudo update-ca-trust extract(Fedora and RHEL). Whencertutilis on your PATH and~/.pki/nssdbexists, Parity also updates that NSS database itself, because Chrome and Chromium read it. Firefox keeps its own store, so Parity prints the manual step: importca.crtunder 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#
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#
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#
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#
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#
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#
| 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 |