px --help lists all commands; px <command> --help shows a command’s options. Offline: init, validate (without --online). Everything else reaches the platform and needs px login first. The CLI is a full alternative to the MCP connection: authoring is declarative (edit files, plan, apply), and every other platform capability — snapshots, policies, templates, apps, queries, search, compute — has a direct command.

px init [DIRECTORY]

Scaffold a workspace skeleton — the JSON Schemas in .px/schemas/, an AGENTS.md guide, a CLAUDE.md pointer, and a worked example of each concept kind. Offline.

px validate [PATH]

Schema + structural checks against the bundled JSON Schemas — offline by default, with a PASS/FAIL exit code. Checks that manifests match their schema, concept bodies have envelopes, output predicates aren’t duplicated, datasource references resolve, and context bodies exist. Also warns when an ontology ships a schema graph but has no concepts (that renders empty on the platform). PATH defaults to searching up from the current directory for prometheux.workspace.yaml.

px login

Authenticate and store URL + token in ~/.prometheux/config.json. See Installation → Authenticate.

px pull [ONTOLOGY]

Export a live ontology into ontologies/<slug>/ (concepts → body + .meta.yaml, datasources, ontology schema, apps). With no ONTOLOGY, lists the ontologies visible to you and exits.

px list <resource>

Browse platform resources. Each subcommand prints the identifier first (the value other commands take) plus a human name.

px plan [PATH]

Diff local files against live server state (read-only). Classifies each concept as create / update / delete and renders the downstream re-run cascade for definition changes; also diffs datasources, ontology schema, and apps.

px apply [PATH]

Apply the plan: connect datasources, then create/update concepts, ontology schema, and apps. Creates the ontology if new; snapshots each ontology first (best-effort). Behaviour:
  • Deletions are safe by default — a concept isn’t deleted just because its file vanished; use --prune. Datasources are user-scoped and never deleted by apply.
  • A datasource already on the account is reused (matched by type/host/port/table), not re-connected — so repeated applies don’t pile up duplicate rows. To disconnect one, use px datasource delete.
  • Best-effort concepts: a concept whose body references something unresolvable (a source defect, or a dep not in this apply) is skipped with a warning; the rest of the ontology still applies, and the run exits non-zero with a skip summary. A genuine error (parse, conflict) aborts fast.
  • Cross-account port: a recreated ontology’s new id is written back to prometheux.yaml, and app project.id references + sibling-output paths are retargeted automatically.

px run CONCEPT [PATH]

Run a concept (an output predicate) and emit OpenLineage START/COMPLETE/FAIL events.

px show CONCEPT [PATH]

Fetch and print the rows of a populated concept (resolved from the local workspace), paginated.

px query ONTOLOGY CONCEPT SQL

Run a read-only SQL SELECT/WITH over one populated concept (aggregates, DISTINCT, GROUP BY) without pulling the workspace. Takes the ontology id and concept name directly.

px test [TARGET]

Unit-test Vadalog programs. Each program runs on the platform engine, and the rows of every expected output predicate are compared with the rows you say it must produce. No workspace is needed, and nothing is saved to an ontology. TARGET is one of:
  • a .vada program, with one --expect PRED=CSV per predicate to check;
  • a *.test.yaml test case;
  • a folder, searched recursively for *.test.yaml cases.
With --question there is no TARGET: the natural-language translator writes the program, and --expect-csv gives the rows it must produce. How rows are compared:
  • An expected CSV has one row per line and no header unless you pass --header. Blank lines are skipped.
  • Values are compared by meaning rather than spelling: 2, "2" and 2.0 are equal, and so are true, True and Vadalog’s #T. Surrounding whitespace is ignored.
  • A declared @output that derives no rows counts as empty, so an empty CSV checks that a predicate produces nothing.
  • A failure lists the rows that are missing and, in exact mode, the rows the program produced but you did not expect, with the values as you wrote them.
px test evaluates on your compute, so a machine must be running (px compute start). Each --question asks the translator for one program, and is counted in your usage as one program generation.

Test case files

A *.test.yaml file names one program, or one question, and the rows each predicate must produce. Paths are relative to the case file, and the case is named after the file.
A question case may also set context, and may give expect as a single CSV or list of rows. Those rows are checked against expect_predicate, or the generated program’s last @output when it is not set.

Running a suite in parallel

--jobs sends several cases to your machine at once. --replicas goes further: it starts engine workers, extra copies of the reasoning engine next to your running machine, and the platform sends each case to whichever engine is least busy, your machine included. When the suite ends (or fails, or you press Ctrl-C) the workers are removed.
  • Workers take time to start: up to a few minutes when they need new nodes, and their first evaluations are slower while the engine warms up. For a small suite, --jobs alone is usually faster.
  • Workers only run test evaluations. Concept runs, apps and everything else stay on your machine.
  • You can run up to 4 workers. Each worker is a node the size of your machine and is billed at your machine’s hourly rate, from when px test asks for it until it is removed. Worker time appears on your invoice under your machine. px test prints the hourly cost when the workers start. Free minutes don’t apply to workers.
  • If the workers aren’t ready within --replicas-timeout, px test exits with code 2.

px search <concepts\|company>

Semantic search across the platform.

px status

Monitor run status account-wide — no workspace needed. One row per ontology (running / success / error / cancelled / interrupted / idle), plus the concept executing and its progress. The engine is globally serialized, so at most one ontology is ever running.

px snapshot <list\|create\|restore\|delete>

Point-in-time snapshots of a server ontology. apply already snapshots before it writes (unless --no-snapshot); these let you manage snapshots directly. All take the ontology id.

px policy <list\|get\|create\|update\|delete\|trigger\|runs>

Evaluation policies run a concept on a cron schedule or when its inputs change. All take the ontology id.

px template <list\|import>

The catalogue of starter ontologies you can clone.

px datasource <preview\|delete>

Connecting datasources is declarative (datasources/*.yaml + apply); these cover the reads and removals apply doesn’t.

px app <publish\|unpublish>

Creating and editing apps is declarative (apps/*.app.yaml + apply); publishing freezes a shareable snapshot of the current draft.

px context <apply\|search>

Manage the context layer (knowledge notes).

px playbook <list\|show>

The platform’s step-by-step skill playbooks (what the AI assistant follows). Distinct from px skill install, which installs the authoring skill into your editor.

px compute <status\|start\|stop\|catalog\|provision\|remove>

Runs need a compute machine. These manage your machines from the terminal.

px delete ONTOLOGY

Permanently delete a whole ontology (a server id or exact name) and everything in it — concepts, datasource binds, ontology schema, apps, notes. The server auto-snapshots first when versioning is available. Local workspace files are not touched. Resolves by id first, then by exact name (ambiguous names must be deleted by id).

px skill install

Install the Prometheux authoring skill into a coding agent, generated from this px’s bundled schemas + guide. See Agent skill.

Exit codes

State & idempotency

  • Ontology id is written into ontologies/<slug>/prometheux.yaml on create — commit it so re-apply targets the same ontology. If lost, apply reconciles by name.
  • Context state (.px/context-state.json) drives idempotent context apply — commit it; if lost, context apply reconciles against server notes by content.
  • A clean pull then plan/apply reports no changes; re-applying is a no-op.