polaris-id-cli

The operator command line for a Polaris ID database: the use-case stored procedures, inspection and read-only queries, and the operator records (users, authorities, quotas, revocation bounds, relying parties, authority keys, retention), without a browser. Polaris ID is pre-pilot software on notional data; the project README says what it is and what it is not.

Not wrapped as subcommands: close_anchor_batch (R10-2), uc10_attest_trust / uc10_revoke_attestation (R11-3), uc11_close_epoch (R10-1), uc12_record_duress (R11-5). Call them through the Flask API with curl.

Install

pip install --pre polaris-id-cli                  # --pre: 1.0.0rc1 is a release candidate
pip install --pre 'polaris-id-cli[user-mgmt]'     # adds werkzeug for user-create and user-passwd
polaris-id --help

Every command talks to a running Polaris PostgreSQL (below). Four also run through modules of the Polaris application, which ship in the repository and not in this package: issue and bulk-enroll sign through polaris_web/pqc_signing, migrate-population uses polaris_web/migration, and transparency-report uses polaris_web/transparency. From a package install those four refuse (exit 2) and say so. Run them from a clone:

git clone https://github.com/EgorKhaklin/polaris-id.git
cd polaris-id/polaris_cli
pip install -e '.[user-mgmt]'
polaris-id issue --help

Configuration

Commands

polaris-id <command> --help lists every flag.

Inspect

polaris-id health
polaris-id list tokens --status ACTIVE
polaris-id list verifications --context BANKING --outcome SUCCESS --limit 20
polaris-id inspect 2
polaris-id query "SELECT context_type, COUNT(*) FROM VerificationEvent ve JOIN VerificationContext vc USING(context_id) GROUP BY context_type ORDER BY 2 DESC"

Use cases

polaris-id issue \
    --legal-name "A. Holder" --dob 1990-01-15 --jurisdiction US-PA \
    --agency 1 --algorithm 1 --token-value TKN-PA-2026-100 --serial SN-PA-100 \
    --biometric IRIS --liveness MULTI_MODAL --witness 2 --hardware TitanQ-3 \
    --contexts 1,4,6

polaris-id activate-reserve --lost-token 4 --reserve-token 7 --actor-agency 1 \
    --reason LOST --crl-url "https://crl.idtoken.gov/2026/05/T4-LOST.crl"

polaris-id bind-device --token 2 --device-type PHONE \
    --fingerprint "SE-AAPL-A19-newdevice12345" \
    --binding-method SECURE_ENCLAVE --validity-months 24

polaris-id warrant-audit --individual 3 --context BANKING \
    --window-start "2026-01-01 00:00:00" --window-end "2026-12-31 23:59:59"

polaris-id transition 2 DORMANT --actor 3 --reason QUARTERLY_REVIEW
polaris-id transition 4 LOST    --actor 1 --reason HOLDER_REPORTED_THEFT

Accounts

Usernames match [a-z0-9._-]{3,50} (lowercased automatically); roles are admin, operator, auditor. Passwords are read interactively with confirmation; --password is for scripting and shows in process listings. Passwords need at least 12 characters with a digit, a letter and a symbol. user-create requires --justification (at least 20 characters, recorded); --actor names who created it.

An admin account gets a 30-day WebAuthn deadline, the same one scripts/polaris-create-operator.sh --role admin sets (docs/design/webauthn.md). During the 30 days a password alone signs in and the interface asks for enrolment; after it, a registered credential is required, and with none the login is refused and the recovery path named. Operator and auditor accounts get no deadline.

polaris-id user-create alice operator --justification "Night-shift issuance operator for PA."
polaris-id user-passwd alice                 # also resets failed_login_count and locked_until
polaris-id user-deactivate alice             # reactivate with a direct SQL update
polaris-id user-history alice --widened-only

audit-log shows logins, failures, lockouts, CSRF rejections, authorization denials, rate-limit triggers, WebAuthn and session events. Rows are append-only at the schema level.

polaris-id audit-log                                        # last 50
polaris-id audit-log --event-type LOGIN_FAILED --since-minutes 60
polaris-id audit-log --username alice --limit 100

Authorities and policy

A --justification is stored with the decision; where one is required it must be at least 20 characters.

Retention is data in RetentionPolicy. STANDARD-5Y keeps every class five years; MINIMIZED keeps the civic record five years and operational history two. Three refusals: below 365 days (a CHECK constraint, so lowering the floor is a schema change); editing or deleting a decision (decisions are superseded, never changed); and a uc_archive_purge cutoff inside the window. See docs/design/retention.md and OPERATIONS.md.

polaris-id retention-show --jurisdiction=US-CA --history
polaris-id retention-set --actor-user-id=7 --jurisdiction=US-CA --template=MINIMIZED
polaris-id retention-set --actor-user-id=7 --jurisdiction=US-CA \
    --table-class=AUTH_AUDIT --days=1095 \
    --justification="State retention schedule 4.2 for operator access records."

Exit codes

Testing

python3 test_cli.py

115 integration tests (v1.0.0-rc.62) cover every command, the user lifecycle (create, authenticate, rotate, deactivate), audit-log filtering and constraint violations. Each test resets the database to the sample state.

Expected output: 115 passed (v1.0.0-rc.62).

Scripting examples

# Bulk-issue from a CSV
while IFS=, read name dob jur token serial; do
    polaris-id issue \
        --legal-name "$name" --dob "$dob" --jurisdiction "$jur" \
        --agency 1 --algorithm 1 --biometric IRIS \
        --token-value "$token" --serial "$serial" \
        --contexts 1,4
done < holders.csv

# Active tokens issued by one agency
polaris-id query "SELECT t.token_id, i.legal_name FROM IdentityToken t
               JOIN Individual i ON t.individual_id = i.individual_id
               WHERE t.issuing_agency_id = 1 AND t.status = 'ACTIVE'
               ORDER BY t.token_id"

# JSON rows for jq
polaris-id query "SELECT row_to_json(t) FROM IdentityToken t WHERE token_id = 2"

# Failed logins per IP in the last hour
polaris-id query "SELECT ip_address, COUNT(*) FROM AuthAuditLog
               WHERE event_type='LOGIN_FAILED'
                 AND event_timestamp > CURRENT_TIMESTAMP - INTERVAL '1 hour'
               GROUP BY ip_address ORDER BY 2 DESC"