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 an Orgonaut bridge import payload.

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.

Export for Orgonaut

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

The Orgonaut export is a bridge payload. It keeps OrgSpec portable while preparing the structure for Orgonaut import tooling:

  • 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

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.