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 byapply. - 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 appproject.idreferences + 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
.vadaprogram, with one--expect PRED=CSVper predicate to check; - a
*.test.yamltest case; - a folder, searched recursively for
*.test.yamlcases.
--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"and2.0are equal, and so aretrue,Trueand Vadalog’s#T. Surrounding whitespace is ignored. - A declared
@outputthat 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
exactmode, 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.
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,
--jobsalone 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 testasks for it until it is removed. Worker time appears on your invoice under your machine.px testprints the hourly cost when the workers start. Free minutes don’t apply to workers. - If the workers aren’t ready within
--replicas-timeout,px testexits 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.yamlon create — commit it so re-apply targets the same ontology. If lost,applyreconciles by name. - Context state (
.px/context-state.json) drives idempotentcontext apply— commit it; if lost,context applyreconciles against server notes by content. - A clean
pullthenplan/applyreports no changes; re-applying is a no-op.

