Skip to content
Parity 0.1.0
Menu

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_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, 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); --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#

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