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.

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.

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 View 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

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.1.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 v0.1 file format.
  • Orgonaut bridge exports are import-preparation files, not the canonical OrgSpec schema.