CLI reference

This page is generated from the nistor command's own argument parser (package nistor-cli), so it lists exactly what the installed CLI accepts. nistor <command> --help prints the same information in a terminal.

Global options#

Given before the command (nistor --api-url https://… rules list).

usage: nistor [-h] [--version] [--api-url API_URL] [--token TOKEN]
              {rules,odcs,patterns,env-mapping,compiler,alerts,deployments,auth,admin,migrate,iam,dist,release,serve,runner,connections,tool}
              ...

Options

Commands

nistor rules#

Manage scheduling rules

usage: nistor rules [-h]
                    {sync,list,approve-match,reject-match,check-platform-targets,validate} ...

Commands

nistor rules sync#

Sync rules from JSON/YAML files to the API

usage: nistor rules sync [-h] --env {dev,test,prod} [--files FILES [FILES ...] | --all | --dir
                         RULES_DIR] [--dry-run] [--delete-orphaned] [--source-repo SOURCE_REPO]
                         [--adopt-rules-without-source-repo] [--source-branch SOURCE_BRANCH]
                         [--continue-on-error] [--output-json OUTPUT_JSON] [--validate]
                         [--require-rules-format] [--record-sync-event]

Options

nistor rules list#

List all rules from the API

usage: nistor rules list [-h]

nistor rules approve-match#

Approve nodes matched by a rule that requires match approval (applies_to.require_match_approval)

usage: nistor rules approve-match [-h] --rule RULE --node NODE [--reason REASON]

Options

nistor rules reject-match#

Reject nodes matched by a rule that requires match approval (applies_to.require_match_approval)

usage: nistor rules reject-match [-h] --rule RULE --node NODE [--reason REASON]

Options

nistor rules check-platform-targets#

Fail unless every platform-job rule the rule files make active in --env is active in the backend and matches a node in the compiled graph: an active rule on no node never fires and nothing reports it. Retried for --wait-seconds (the backend lists rules from a lagging read replica). With --compile-job, rules that still match no node start one compile (the graph may predate the compiler just deployed) and the check re-runs for --compile-wait-seconds. CI runs it right after the rules sync in the deploy job's config sync

usage: nistor rules check-platform-targets [-h] --env {dev,test,prod}
                                           (--files FILES [FILES ...] | --all | --dir RULES_DIR)
                                           [--wait-seconds WAIT_SECONDS] [--compile-job NAME]
                                           [--compile-project PROJECT] [--compile-region REGION]
                                           [--compile-wait-seconds COMPILE_WAIT_SECONDS]

Options

nistor rules validate#

Check rule files offline (no API): parse, code_id/name duplicates, and every payload the sync would send against this checkout's rule schema, including fields the backend would silently drop

usage: nistor rules validate [-h] (--files FILES [FILES ...] | --all | --dir RULES_DIR)

Options

nistor odcs#

Manage ODCS data contracts (config-as-code)

usage: nistor odcs [-h] {sync} ...

Commands

nistor odcs sync#

Sync *.odcs.yaml contracts from the repo to the API

usage: nistor odcs sync [-h] --env {dev,test,prod} [--files FILES [FILES ...] | --contracts-dir
                        CONTRACTS_DIR] [--dry-run] [--delete-orphaned] [--source-repo SOURCE_REPO]
                        [--source-branch SOURCE_BRANCH] [--continue-on-error]
                        [--output-json OUTPUT_JSON]

Options

nistor patterns#

Manage resource patterns

usage: nistor patterns [-h] {sync,list} ...

Commands

nistor patterns sync#

Sync resource patterns from JSON file to the API

usage: nistor patterns sync [-h] [--file FILE] [--dry-run] [--allow-deletions]

Options

nistor patterns list#

List all resource patterns from the API

usage: nistor patterns list [-h]

nistor env-mapping#

Manage environment mappings

usage: nistor env-mapping [-h] {sync,show} ...

Commands

nistor env-mapping sync#

Sync environment mappings from JSON file to the API

usage: nistor env-mapping sync [-h] [--file FILE] [--dry-run]

Options

nistor env-mapping show#

Show current environment mappings from the API

usage: nistor env-mapping show [-h]

nistor compiler#

Manage compiler configuration

usage: nistor compiler [-h] {sync,show} ...

Commands

nistor compiler sync#

Sync compiler config from JSON file to the API

usage: nistor compiler sync [-h] [--file FILE] [--dry-run]

Options

nistor compiler show#

Show current compiler configuration from the API

usage: nistor compiler show [-h]

nistor alerts#

Manage alert channels, policies & email settings

usage: nistor alerts [-h] {sync,list} ...

Commands

nistor alerts sync#

Sync alert channels/policies/email from JSON to the API

usage: nistor alerts sync [-h] --env {dev,test,prod} [--dir ALERTS_DIR]
                          [--channels-file CHANNELS_FILE] [--policies-file POLICIES_FILE]
                          [--email-file EMAIL_FILE] [--dry-run] [--delete-orphaned]
                          [--source-repo SOURCE_REPO] [--source-branch SOURCE_BRANCH]
                          [--continue-on-error] [--output-json OUTPUT_JSON]

Options

nistor alerts list#

List alert channels and policies from the API

usage: nistor alerts list [-h]

nistor deployments#

Deployment provenance: report what a deploy put in place

usage: nistor deployments [-h] {record} ...

Commands

nistor deployments record#

Report the resources a deploy manages (POST /api/v1/deployments/reports). Best-effort by default: a report that cannot be delivered is one warning and exit 0; only an unreadable or invalid input file exits 1. --fail-if-not-recorded makes a non-delivered report exit 3 too, for a caller that wants to know

usage: nistor deployments record [-h] --provider {terraform,nistor-install} --tf-show-json FILE
                                 [--env {dev,test,prod}] [--repo REPO] [--ref REF]
                                 [--commit COMMIT] [--pipeline-url PIPELINE_URL]
                                 [--deployed-by DEPLOYED_BY] [--dry-run] [--fail-if-not-recorded]

Options

nistor auth#

Authentication utilities

usage: nistor auth [-h] {test} ...

Commands

nistor auth test#

Test API connectivity and authentication

usage: nistor auth test [-h]

nistor admin#

Tenant admin operations (users, permissions, audit)

usage: nistor admin [-h] {user,audit} ...

Commands

Examples:
  nistor admin user list
  nistor admin user grant alice@example.com iam:view
  nistor admin user revoke alice@example.com iam:view
  nistor admin audit export --since 7d --format csv
  nistor admin user list-permissions --format json

nistor admin user#

Manage users and their permissions

usage: nistor admin user [-h] {list,list-permissions,grant,revoke} ...

Commands

nistor admin user list#

List users

usage: nistor admin user list [-h] [--format {table,json,csv}]

Options

Example: nistor admin user list --format csv

nistor admin user list-permissions#

List the catalog of permission codes

usage: nistor admin user list-permissions [-h] [--format {table,json,csv}]

Options

Example: nistor admin user list-permissions --format json

nistor admin user grant#

Grant a permission to a user

usage: nistor admin user grant [-h] [--format {table,json,csv}] email permission

Arguments

Options

Example: nistor admin user grant alice@example.com iam:view

nistor admin user revoke#

Revoke a permission from a user

usage: nistor admin user revoke [-h] [--format {table,json,csv}] email permission

Arguments

Options

Example: nistor admin user revoke alice@example.com iam:view

nistor admin audit#

Inspect the audit log

usage: nistor admin audit [-h] {export} ...

Commands

nistor admin audit export#

Export audit log entries (newest first)

usage: nistor admin audit export [-h] [--since SINCE] [--format {table,json,csv}]

Options

Example: nistor admin audit export --since 7d --format csv

nistor migrate#

Migrate the database: core, then tools, then plugins

usage: nistor migrate [-h] [--core-script-location CORE_SCRIPT_LOCATION] [--only ONLY]
                      [--uninstall CHAIN] [--policy {keep,archive,drop}] [--purge]
                      [--release-id RELEASE_ID] [--lock-digest LOCK_DIGEST] [--check-gap LOCK]

Options

nistor iam#

IAM operations run inside the runtime image

usage: nistor iam [-h] {register-service} ...

Commands

nistor iam register-service#

Register a service principal (a service-account e-mail or system:serviceaccount:<ns>:<sa>); never an admin; idempotent

usage: nistor iam register-service [-h] [--permission CODE] principal

Arguments

Options

nistor dist#

The distribution's lock: make it, check it

usage: nistor dist [-h] {lock,build,verify,grants} ...

Commands

nistor dist lock#

Write distribution.lock from distribution.toml

usage: nistor dist lock [-h] --env-dir ENV_DIR [--source-dir NAME=PATH] [--today TODAY]
                        [--wheel-dir WHEEL_DIR] [--prepare-local]

Options

nistor dist build#

Build the runtime image from distribution.lock

usage: nistor dist build [-h] --env-dir ENV_DIR [--source-dir NAME=PATH] [--today TODAY]
                         [--tag TAG] [--wheel-dir WHEEL_DIR] [--recipe-tree RECIPE_TREE]
                         [--context CONTEXT] [--docker DOCKER]

Options

nistor dist verify#

Check distribution.lock, an image built from it, or this environment

usage: nistor dist verify [-h] [--env-dir ENV_DIR] [--source-dir NAME=PATH] [--today TODAY]
                          [--offline] [--image IMAGE] [--installed] [--document DOCUMENT]

Options

nistor dist grants#

Print the grants the locked tools require (read-only)

usage: nistor dist grants [-h] LOCK

Arguments

nistor release#

Release trains: versions, tags, changelog, names

usage: nistor release [-h] {prepare,verify-tag,parse-tag,members,changelog,notes,names} ...

Commands

nistor release prepare#

Write a train's version into its files

usage: nistor release prepare [-h] [--root ROOT] train version

Arguments

Options

nistor release verify-tag#

Exit 1 unless the files carry the tag's version

usage: nistor release verify-tag [-h] [--root ROOT] tag

Arguments

Options

nistor release parse-tag#

Print a tag's train and version (exit 2 unless it is a release tag)

usage: nistor release parse-tag [-h] tag

Arguments

nistor release members#

List a train's member paths

usage: nistor release members [-h] [--kind {python,npm,app,text}] [--root ROOT] train

Arguments

Options

nistor release changelog#

Notes for a release from the train's commit subjects

usage: nistor release changelog [-h] [--since SINCE] --version VERSION [--date DATE] [--write]
                                [--root ROOT]
                                train

Arguments

Options

nistor release notes#

Print one version's section of the train's CHANGELOG.md (exit 2 if none)

usage: nistor release notes [-h] [--train TRAIN] [--root ROOT] version

Arguments

Options

nistor release names#

The PyPI and npm names the releases publish

usage: nistor release names [-h] [--format {json,text}] [--root ROOT]

Options

nistor serve#

Start one server role of the runtime image

usage: nistor serve [-h] [--port PORT] [--host HOST]
                    {backend,scheduler,jobs,compiler,input-logs,mcp,runner,workspace-events,dq-rebuild}

Arguments

Options

nistor runner#

Edge runner utilities

usage: nistor runner [-h] {keygen} ...

Commands

nistor runner keygen#

Write an edge runner's Ed25519 key pair (private key 0600) and print the public key to register

usage: nistor runner keygen [-h] --out OUT

Options

Example: nistor runner keygen --out ./runner-key   (then mount it at /etc/nistor/runner)

nistor connections#

Manage tool connections

usage: nistor connections [-h] {create-gcp-from-env,sync} ...

Commands

nistor connections create-gcp-from-env#

Create a GCP connection from the pre-phase-2 environment variables (local development only)

usage: nistor connections create-gcp-from-env [-h] --name NAME [--billing-project BILLING_PROJECT]
                                              (--impersonate IMPERSONATE | --service-account-json SERVICE_ACCOUNT_JSON | --application-default)
                                              [--monitored-projects MONITORED_PROJECTS]
                                              [--locations LOCATIONS] [--default] [--dry-run]

Options

Example: nistor connections create-gcp-from-env --name local-gcp --application-default --dry-run

nistor connections sync#

Upsert connections from a JSON file by name (create missing, update changed; never deletes)

The file is a JSON array of connections (or an object with a "connections" list); each has the shape create-gcp-from-env prints (name, tool_type or type, config, secrets, is_default; optionally description, cadence_minutes, status). {ENV} resolves against --env; ${VAR} is expanded from the environment in secrets only. An existing secret key is never rewritten (rotate it instead); a new secret key is added.

usage: nistor connections sync [-h] --env {dev,test,prod} --file FILE [--dry-run]

Options

Example: nistor connections sync --env dev --file config/connections.json --dry-run

nistor tool#

Build a tool package for Nistor

usage: nistor tool [-h] {new} ...

Commands

nistor tool new#

Scaffold a tool package (manifest, health probe, executor, connection spec, conformance test) from the template; it passes the tool conformance kit as generated

usage: nistor tool new [-h] [--dest DIR] id

Arguments

Options

Example: nistor tool new acme_warehouse --dest .   (writes ./packages/integrations/acme_warehouse)