ORGONAUT
Login Signup
Docs
Agents and API
OrgSpec CLI

OrgSpec CLI

OrgSpec CLI is a standalone file utility for organisation structure data. It does not require an Orgonaut account for local commands.

Use it when you need to turn HR exports or spreadsheets into portable org-structure files, validate them, render diagrams, compare changes, or prepare data for Orgonaut.

OrgSpec 0.2 also describes the operating model around the chart: Work activities, business capabilities and measures, governed AI Solution versions, obligations, and deployments. It keeps people, agents, robots, structure, work, outcomes, and enabling solutions in one portable document.

Install

Bash
curl -fsSL https://app.orgonaut.co/orgspec/install.sh | sh

The installer detects macOS or Linux and installs the matching binary as orgspec.

Basic workflow

Bash
orgspec init --out org.orgspec.yaml
orgspec validate org.orgspec.yaml
orgspec render org.orgspec.yaml --format mermaid --out org.mmd
orgspec render org.orgspec.yaml --format svg --out org.svg

Import a CSV

Bash
orgspec import people.csv \
  --mapping manager_email \
  --format json \
  --out org.orgspec.json \
  --org-id acme \
  --org-name "Acme Ltd"

Supported initial mapping presets are:

  • manager_email
  • manager_id
  • department_path

Diff two org files

Bash
orgspec diff january.orgspec.json february.orgspec.json --format markdown --out org-diff.md
orgspec diff january.orgspec.json february.orgspec.json --format json --out org-diff.json

Diffs detect actor changes, actor-kind changes, unit moves, reporting changes, placement changes, and position or vacancy changes. For OrgSpec 0.2 files, diffs also report changes across Work, Capability, and Solution collections.

Work, Capabilities, and Solutions

Use orgspec: "0.2" when a document includes operating-model data. The main collections are:

  • work_categories, work_activities, and work_assignments
  • capabilities, contextual capability_assessments, Work mappings, measures, and dated values
  • solutions, immutable version specifications, claims, obligations, and contextual deployments

Each document represents one state or planning context. Scenario and snapshot IDs are intentionally excluded. A consuming tool decides whether the file becomes a Live model, a proposed scenario, or another comparison point.

A Solution is a reusable governed asset, not an actor. A deployment can reference an agent_actor when the exact solution version powers or supports an AI actor in the org model.

Import into Orgonaut

Bash
orgspec validate org.orgspec.yaml

Open Orgonaut, go to Imports, choose New Import, and upload org.orgspec.yaml directly. Canonical OrgSpec YAML is the primary import format. Canonical OrgSpec JSON is also supported.

The wizard validates the document and previews actor, unit, position, and placement counts before you choose the Live Baseline or a new scenario as the target:

  • OrgSpec actor person maps to Orgonaut actor human
  • agent and robot actor kinds are preserved
  • units map to Orgonaut org units
  • department and team units include metadata rows where applicable
  • placements convert allocation ratios to percentages
  • the target tenant and Live/scenario import context are supplied by Orgonaut, not stored inside the OrgSpec file
  • stable OrgSpec IDs are retained so later imports update matching records
  • unsupported protocol fields are retained as OrgSpec metadata
  • OrgSpec 0.2 operating-model collections are validated and retained on the import run/bridge; the current structural importer does not yet materialize them into Work, Capability, and Solution records

For existing automation, Orgonaut continues to accept the versioned bridge format:

Bash
orgspec export org.orgspec.yaml --format orgonaut --out orgonaut-import.json

The bridge is an advanced compatibility payload, not the preferred manual upload. If an entity cannot be imported, Orgonaut quarantines the source record. Correct the canonical OrgSpec document, validate it, and import it again.

Versioned installs

Install the latest release:

Bash
curl -fsSL https://app.orgonaut.co/orgspec/install.sh | sh

Install a specific release:

Bash
curl -fsSL https://app.orgonaut.co/orgspec/install.sh | ORGSPEC_VERSION=v0.2.0 sh

Install to a user-writable directory:

Bash
curl -fsSL https://app.orgonaut.co/orgspec/install.sh | ORGSPEC_INSTALL_DIR=$HOME/.local/bin sh

Notes

  • OrgSpec is a portable file format and CLI utility. It is distributed as a binary from Orgonaut-hosted release artifacts.
  • Local commands do not make network calls.
  • Scenario and snapshot concepts are intentionally outside the OrgSpec file format.
  • Orgonaut bridge exports are import-preparation files, not the canonical OrgSpec schema.