Get started with Orvienm

Orvienm is distributed as a Source-Access Alpha. There is no package index entry and no binary release yet, so pip install orvienm will not resolve — you install from the public source repository, orvienm-polaris. Python 3.10 or newer is required.

git clone https://github.com/kw13j1qs0/orvienm-polaris.git
cd orvienm-polaris
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install .

git clone https://github.com/kw13j1qs0/orvienm-polaris.git
cd orvienm-polaris
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .

To work on the CLI itself, install it in editable mode with python -m pip install -e . and run the test suite that ships with it using pytest.

Confirm the CLI is on your path and see what it exposes.

orvienm --version
orvienm --help

Create a working directory and put a specification in it. A specification names the structure and lists the directories it should contain. structure.name is the directory Orvienm will create, resolved relative to where you run the command — so the file below produces platform/core, platform/data platform/docs.

version: 1

structure:
  name: platform
  directories:
    - core
    - data
    - docs

Entries may contain forward slashes. A nested entry such as services/api creates the intermediate directory too, and plan, verify doctor all account for it.

Every key and rule the format accepts is listed in the Specification Reference.

Validation reads the specification and checks it. Nothing touches the filesystem. Every other command runs this first, so a failure here stops the lifecycle.

orvienm validate .orvienm.yaml

A valid file prints Validation successful and exits 0. A malformed one prints every problem it found and exits 1; Troubleshooting explains each message.

Plan compares the declared structure against what is on disk and prints the difference. It changes nothing.

Orvienm Plan
────────────────────

+ create platform/
  + create core/
  + create data/
  + create docs/

Plan Summary
────────────────────
Create:     4
Keep:       0
Undeclared: 0

Once directories exist they appear as keep. A directory that exists but is not declared appears as undeclared. Apply neither creates nor removes it — plan names no operation the engine will not perform.

Apply creates the root and every declared directory inside it. Directories that already exist are left as they are, and directories Orvienm did not declare are left untouched.

orvienm apply .orvienm.yaml

On the first successful apply Orvienm writes .orv.lock in the working directory, recording its fingerprint. Use --dry-run to print what would be created without creating it.

Verify checks that every declared directory exists and prints Status: VALID or Status: INVALID. It exits 0 when the structure is complete and 2 when it is not, so it can gate a pipeline directly.

orvienm verify .orvienm.yaml
orvienm status .orvienm.yaml
orvienm doctor .orvienm.yaml

status adds the lock file and fingerprint to the picture and exits 2 if anything needs attention. doctor goes further and also reports directories present on disk but absent from the specification. On a workspace that matches its specification, all three are clean.

doctor reports by default and exits 0 whatever it finds. In a pipeline, use orvienm doctor .orvienm.yaml --strict, which exits 2 on any diagnosis other than HEALTHY. It detects exactly the same things either way — only the exit code changes.

orvienm new writes an example project you can edit rather than starting from a blank file.

orvienm new my-project
orvienm validate my-project/.orvienm.yaml

Run the lifecycle commands from the directory that contains my-project/, not from inside it: structure.name is resolved relative to the working directory, so applying from inside would create a second nested root.

orvienm init is the other way in, and it writes the specification where you are standing rather than inside a new directory. The name you give it is the root it declares.

mkdir work && cd work
orvienm init platform
orvienm plan
orvienm apply

That produces work/.orvienm.yaml and work/platform/. init only writes the specification — apply is what creates directories, here as everywhere — so the first plan shows the whole structure as pending and the second shows Create: 0.