peart CLI

peart is the internal-surface binary: the API under /api/v1, the pentester interface, and the administrative commands that own the data. The client portal is a separate program with its own entry point, documented in peart-portal CLI.

Every subcommand is listed by peart help, and every one of them prints its own flags with peart <command> -h. This page is the same information with the reasons and the examples that a flag's one-line description has no room for.

How a command is spelled

Flags are parsed by Go's standard library, which accepts -config and --config as the same flag. This page writes one dash, because that is the form peart <command> -h prints back. Values may be given as -config /etc/peart/config.yaml or -config=/etc/peart/config.yaml.

An invocation that asks for help writes it to standard output and exits 0. An invocation the binary cannot parse writes the same text to standard error and exits 2, so a script can tell the two apart without reading the message.

Most commands accept -config, and it means the same file peart serve reads. Where a command also accepts a direct path such as -db, the direct path wins over what the configuration says, which is what makes one-off work on a copy of the database possible without editing configuration.

Running the surface

Flag	Default	What it is
-config	/etc/peart/config.yaml	The configuration file, read at startup and never again

peart serve -config /etc/peart/config.yaml

The process checks the schema version before it listens. A database older than the binary makes it refuse to start rather than migrate on the way up, so an upgrade is always a step somebody took on purpose. See Upgrading.

Preparing and upgrading the database

Flag	Default	What it is
-config	none	Configuration file to read db_path from
-db	none	Path to the SQLite database, overriding db_path

sudo -u peart peart migrate -config /etc/peart/config.yaml

migrate applies every pending migration or none at all, and then imports the bundled techniques and methodologies. Running it again on an up-to-date database is a no-op, which is what makes it safe in a deployment script that does not know what state it is arriving at.

Accounts

user carries four actions, each with its own flags. All four take -db, and the database path is not read from the configuration file for them, so it is given directly.

Action	Required flags	What it does
create	-db, -email, -name, -role	Creates an account and prints a single-use enrollment link
list	-db	Lists accounts with their role and state
deactivate	-db, -id	Deactivates an account, keeping everything it authored
reset-totp	-db, -id	Clears the second factor so the holder enrols again

peart user create \
  -db /var/lib/peart/peart.db \
  -config /etc/peart/config.yaml \
  -email ana@exemplo.test -name "Ana Souza" -role pentester

-config is optional here and does one thing: it supplies internal.public_url, which is what turns the enrollment token into a link somebody can click. Without it the command prints the raw token and says so, rather than inventing a hostname that may not be the one the person will reach.

role is admin or pentester. An account is never deleted, only deactivated, because findings, evidence and report versions carry their author and a deleted row would leave that trail pointing at nothing.

Backups, keys and integrity

Command	Required	Also accepts
backup	-out	-config, -db, -evidence-root, -rendition-root, -key
backup-roundtrip	none	the same flags as backup, without -out
export-key	-key, -confirm	none
fsck	none	-config, -db, -evidence-root

peart backup -config /etc/peart/config.yaml -out /var/backups/peart

One artifact holds a consistent snapshot of the database, the evidence and the renditions. The master key is deliberately not in it: a backup that carried its own key would be a single file that decrypts itself, and the point of the key is that it lives somewhere else.

peart backup-roundtrip -config /etc/peart/config.yaml

Backs up into a temporary directory, restores into a second one, and opens the restored database to confirm it is a queryable SQLite file rather than bytes that happen to pass a checksum. Both directories are removed before it returns. Run it on the schedule you run backups on: an untested backup is not a backup.

peart export-key -key /etc/peart/master.key -confirm

-confirm is required and is not a formality: it acknowledges that whoever holds this output can read every evidence file, and that losing the key loses all of them. Keep the export somewhere the data backup is not.

peart fsck -config /etc/peart/config.yaml

Reports evidence files that are missing, hashes that no longer match, and derived state that has drifted from what produced it. It reports; it does not repair.

Reading the effective configuration

Flag	Default	What it is
-config	/etc/peart/config.yaml	The file to read

peart config -config /etc/peart/config.yaml

Prints the configuration as the process actually resolved it, environment overrides included, with every sensitive value masked. It is the first thing to run when a setting seems not to be taking effect, because it answers what the program read rather than what the file says.

Evaluating with demo data

Flag	Default	What it is
-config	none	Configuration to read db_path, master_key_path and evidence_root from
-db, -key, -evidence-root	none	Direct paths, each overriding the configuration
-catalog	the bundled web baseline	Framework catalogue the seeded engagement adopts

peart seed -config /etc/peart/config.yaml

Populates one fictional engagement with findings, evidence and a report, which is what makes screenshots, bug reports and a first look possible without inventing a client. It touches no internal account and no second factor. It is for evaluation, not for a database that holds real work.

Repository gates, which an operator never runs

The last entries in peart help are checks this repository runs against itself: spec-diff, portal-fieldcheck, i18n-check, severity-rank-check, tracked-binary-check, js-syntax and sbom-merge-frontend. They read the source tree, not a deployment, and the make targets invoke them. They are listed here so that seeing them in peart help is not a puzzle; what each one gates is in Development-lifecycle security.