This guide takes you from nothing to a running concept on the platform. It assumes px is installed.
init and validate are fully offline — you can author and validate a whole workspace before you have an account. Only login, plan, apply, and run reach the platform.

​
Author from scratch → apply

1

Scaffold a workspace

This writes a starter workspace: the JSON Schemas under .px/schemas/, an AGENTS.md authoring guide, and a worked example of each concept kind under ontologies/example/.
2

Author your files

Edit the example, or add your own. A concept is a body file plus a .meta.yaml envelope. For example, ontologies/example/concepts/customers.vadalog:
and its customers.meta.yaml:
See Authoring a workspace for the full file model.
3

Validate (offline)

Runs schema + structural checks and prints PASS or FAIL. Loop on this until it’s green — it needs no platform connection.
4

Authenticate

5

Preview with plan

plan pulls current server state and shows exactly what apply would do — create / update / delete per concept, plus the downstream re-run cascade for any definition change. Nothing is written.
6

Apply

Connects datasources, then creates/updates concepts, ontology, and apps. A brand-new ontology is created and its server id is written back into prometheux.yaml — commit that so the next apply targets the same ontology.
7

Run a concept

Runs the concept, materializes its output, and emits OpenLineage events. Watch progress across your account any time with px status --watch.

​
Pull an existing ontology → edit → apply

Already have an ontology on the platform? Bring it down to files:
A clean pull always plans as “no changes” — the file format round-trips faithfully.

​
Set up an agent to do this for you

Install the skill and let Claude Code or Cursor drive the same loop:
Then ask your agent: “Add a concept that flags customers in high-risk countries, downstream of risk_score, and apply it.” It writes the files, runs px validate until green, reads px plan, and runs px apply. See Agent skill.

​
Where to next

Authoring a workspace

Manifests, concept kinds, datasources, the derived graph.

Context as code

Keep your knowledge notes in the repo and sync them.

Command reference

Every command and flag.

CI/CD

Apply from GitHub Actions on every merge.