Skip to content

The CLI design

The target CLI, from the owner's voice session of 2026-10-25 (raw data in Drive #pontos/raw/2026-10-25, files 38 to 47; the flow in last-terminal.html). It wins over any legacy command: the commands of today's code (platform ...) are reference only, mapped below.

Every command lives in a deck, one per reef (#477): docs/specs/cli/reefs/<reef>.yaml, with a section per kind and the index in docs/specs/cli/index.yaml. The YAML is the source of truth, an outline of the deck engine (docs/presentations/render-outline, Decks); each command slide has a status (built, planned with its issue, or idea), shown as a tag after its label.

A new command, or a change to one, goes into its reef's deck first, and the issue that builds it points to the slide (reefs/edge.html#domain-get). The get-started, release and edge decks in docs/walkthrough/decks/ link each step to its command's slide; the engine refuses a link to a slide that does not exist.

make decks renders them all; make deck-test checks them and fails when an HTML is stale. The reefs not ported yet keep their commands in this page and in the walkthroughs.

The words

Word What it is Legacy word
reef A capability of the platform, an API group <reef>.getnereus.dev/v1alpha1 (for example secrets.getnereus.dev/v1alpha1). A reef can exist with no Nereid; then it waits. core is built in. Interface
Nereid A controller installed in the platform, top-level, with a name global to the platform. One Nereid may look after many reefs (--reef repeats), and one reef may have many Nereids. It owns its authentication (for example workload-identity) and its default target parameters (for example a default vaultUrl). Its image is <reef>-<tool>-controller. Implementation
Mandate Binds one reef to one Nereid, top-level. It may override the Nereid's target parameters with --param (a Nereid may serve several vaults); --default makes it the reef's default; --match <key>=<value> picks it for the requests whose keys equal the values, the most specific match winning (ADR 0017, #1598). Class
tenancy The reef that holds whose a thing is (ADR 0015): tenancy.getnereus.dev/v1alpha1, its kinds from each instance's reefs/tenancy/ (here Organization, the boundary, and Project), every kind a node with spec.parent: {kind, name}. Its commands are ideas in its deck (#569) until #573 builds them. none
catalog The reef that says what Nereus has (ADR 0016): catalog.getnereus.dev/v1alpha1, its kinds Workload (what runs, the default kind, so nereus catalog list is nereus catalog workload list), Package (what is published), the configurable WorkloadType and PackageType, and Template (its render is the delivery deck's). Every entry names its owner and a Workload its audience; source.ref is structured as Flux's (--ref <field>=<value>, repeatable, never one string); --audience none is audience: []. Its commands are ideas in its deck (#570) until #574 builds them. none
delivery The reef that takes a Workload to an Environment (ADR 0020): delivery.getnereus.dev/v1alpha1, its kind Delivery (the default kind), one per pair. nereus workload deploy writes it, and the Nereid kubernetes resolves the image's digest and writes a Release. Its commands are planned in its deck until #845 builds them. none
database The first resource reef (ADR 0017, #653): database.getnereus.dev/v1alpha1, its kind Database (the default kind, so nereus database create) with owner: {kind, name} in the tenancy tree, which must exist, and engine (postgres), in the nereus namespace only; the Nereid cloudnative-pg of its default Mandate cloudnative-pg (applied by the internal-developer-platform profile) writes in status.binding.secret the Secret of the connection. none
messaging A resource reef (ADR 0017, #1597, the first cut of #576): messaging.getnereus.dev/v1alpha1, its kinds Topic and Queue (no default kind, so nereus messaging topic create and nereus messaging queue create, next to nereus messaging session) with owner: {kind, name} in the tenancy tree, engine (nats) and deletionPolicy (retain, the default, or delete), in the nereus namespace only; the Nereid nats of the admin's default Mandate (--param jetstream=true) runs NATS next to it and writes in status.binding.secret the Secret <name>-topic or <name>-queue. none
registry The reef that runs a registry of images in the cluster (ADR 0021): registry.getnereus.dev/v1alpha1, its kinds Registry (the default kind) and Repository (#1013, its own push credential). The Nereid writes status.pullAddress for a node and status.internalAddress for a Pod. Not the Nereid registry (#22). See its deck. none
scm The reef that holds what a source host is to Nereus (ADR "The scm reef", #927): scm.getnereus.dev/v1alpha1, its kind Connection (one organisation of a host, reached through the GitHub App that its scm Mandate's param identity names; the default kind). Who the platform is towards the host (the App, a short-lived Token) is the authentication reef's (ADR 0006). The github Nereid serves both reefs, opt-in. See its deck. none
owner Whatever points to the tenancy tree names owner: {kind, name}, a kind of the tenancy group, never an apiVersion or a namespace: the catalog's Workloads and Packages, an Environment, a resource Instance, a Mandate's match. On the command line --owner <kind>/<name>, optional once nereus config set owner names the current one; the flag wins and the output line names the owner used. spec.project
target What nereus init --target <provider> prepares (for azure: Key Vault, Storage, DNS zone, Managed Identity), with the person's own login, since no Nereid exists yet. --target of platform init

"Mandate" is the working term, and "Instance" keeps its name (ADR 0002). The CLI binary is nereus (formerly platform, #396); its commands are the ones below since #409, and the legacy ones are deprecated aliases (see Legacy commands).

The commands

# Prepare a cluster: core, then a profile (ADR 0014). core, the default: core only;
# internal-developer-platform: authentication with keycloak, after the secrets reef it
# requires (OpenBao on k3d, its default vault Mandate and RSA key)
nereus init
nereus init --profile internal-developer-platform
nereus init --target azure

# Profiles (ADR 0014): one YAML file each, charts/nereus/profiles/<name>.yaml, rendered by the chart
# into the Profile's spec, which thetis reads alone (spec.reefs required, #1370); apply layers one on core, idempotent, and
# `init --profile <name>` is init, then this. `profile create` is parked
nereus profile list
nereus profile describe <profile>
nereus profile apply <profile> [--without <nereid>]... [--dry-run]   # on a Profile (the charts), --without leaves a Nereid out (#1231); the Nereids install side by side, NEREUS_PROFILE_LANES at once (4, #1297)

# Reefs (after the profile internal-developer-platform, `reef create secrets` fails as "already exists",
# `reef apply secrets` reports unchanged or configured)
nereus reef list
nereus reef apply <reef> --from-file ./reefs/<reef>/

# Nereids
nereus nereid suggest --reef <reef>
nereus nereid apply <nereid> --reef <reef> [--reef <reef> ...] [--image <image>] [--param <key>=<value> ...]

# Mandates
nereus mandate create <mandate> --reef <reef> --nereid <nereid> [--param <key>=<value> ...] [--match <key>=<value> ... | --default]

# The reefs' own commands: nereus <reef> <kind> <verb> <name>; `nereus <reef> <verb>` is the
# reef's default kind (ADR 0013), so `nereus secrets create` is `nereus secrets secret create`.
# create builds from flags, apply takes files or folders of .yaml
nereus secrets create <secret> --from-env <variable> [--from-env <variable> ...]
nereus secrets create <secret> --from-env <variable> --dry-run --output yaml > <file>
nereus secrets apply --from-file <file or folder>

# The release reef (ADR 0010, #445): a kind named after its reef takes the reef's own verbs,
# so `nereus release create` is `nereus release release create`
nereus release repository create|apply|list|get|delete <repository> [--url <url> --type http|oci|git] [--secret <secret>]
nereus release source create|apply|list|get|delete <source> [--repository <repository> --chart <chart> --version <version>]
nereus release target create|apply|list|get|delete <target> [--namespace <namespace>] [--environment <environment>]
nereus release create|apply|list|get|delete <release> [--source <source> --target <target>] [--values-file <file>] [--mandate <mandate>]
nereus release get <release> --watch

# The tenancy reef (ADR 0015, ideas in its deck until #573): parents before children,
# the output names each node by its full path (#647); a flag per string field of the
# kind's spec; apply is the group's, never a kind's; spec.parent never changes (#646)
nereus tenancy organization create|list|get|delete <organization>
nereus tenancy project create|list|get|delete <project> [--parent <kind>/<name>] [--repository <url>] [--cascade]
nereus tenancy apply --from-file tenancy/ [--dry-run]

# The catalog reef (ADR 0016, built by #902, check an idea until #903): workload is the default kind;
# apply is the group's, never a kind's; a template writes files before the catalog, so
# --template is not a flag of create (its render is the delivery deck's); check fails on a
# contradiction (✗) and only points at a gap (!)
nereus catalog workload create|list|get|delete <workload> [--owner <kind>/<name>] [--type <type>] [--audience programs|people|agents|none] [--repository <url>] [--ref <field>=<value>] [--path <path>]
nereus catalog package create|list|get|delete <package> [--owner <kind>/<name>] [--type <type>] [--registry <registry>] [--name <name>] [--audience <audience>]
nereus catalog workload-type create|list|get|delete <type> [--runs always|once] [--trigger event|request|schedule]
nereus catalog package-type create|list|get|delete <type> [--registry <registry>]
nereus catalog apply --from-file catalog/ [--dry-run]
nereus catalog check

# The delivery reef (ADR 0020, planned in its deck until #845): deploy never guesses the
# target; workload list is the catalog's, delivery list is what was deployed
nereus workload deploy <workload>@<environment>|<delivery> --image <reference> [--wait] [--timeout <seconds>] [--dry-run]
nereus workload list
nereus workload logs <workload>@<environment>|<delivery>|<workload> [--environment <environment>] [--follow]
nereus delivery create|list|get|delete <delivery>
nereus delivery apply --from-file <path> [--wait=true|false] [--timeout <seconds>] [--dry-run]
nereus template render <template> --path <folder> [--param <name>=<value>] [--dry-run]

# The registry reef (ADR 0021): the zot Nereid is #1012, Repository and publish are #1013
nereus registry create <registry> [--owner <kind>/<name>] [--mandate <mandate>] [--dry-run]
nereus registry list|get|delete <registry>
nereus registry apply --from-file <path> [--wait=true|false] [--timeout <seconds>] [--dry-run]
nereus registry repository publish <repository> --registry <registry> --image <image>:<tag>
nereus registry repository list|get|delete <repository>

# The platform's identity (ADR 0006, planned in the authentication deck): a GitHub App is a Mandate
# of the opt-in github Nereid (#1273), its key a plain secret; Token is #1274, the browser action #1275
nereus nereid apply github --reef authentication --reef scm
nereus mandate create github --reef authentication --nereid github --param appId=<id> --param privateKey=<secret> --param allow=<namespace>:<repository or *>:<permission>=<level>[,...] [--default]
nereus authentication token create <token> --repository <org>/<repository> [--permission <name>=<access>] [--mandate <mandate>] [--dry-run]
nereus authentication token list|get|delete <token>

# The scm reef (ADR 0024, built in #1281): a Connection names an organisation
# reached through the App its scm Mandate names (--param identity=<authentication mandate>, #1281); no vendor, no key, no verify
nereus scm connection create <connection> --org <org> [--mandate <mandate>] [--default] [--dry-run]
nereus scm connection list|get|delete <connection>

# The current owner (ADR 0016, with #574): --owner becomes optional; the flag wins
nereus config set owner <kind>/<name>

# How the reefs are doing
nereus status

# Whether this instance is healthy: pass or fail per check, exit code 1 when one fails (#799)
nereus doctor

# The CLI keeps itself up to date (#1782): upgrade now, or only report; a normal call starts a
# detached upgrade once per check_interval (auto_upgrade: background, notify or off)
nereus upgrade [--check|--dry-run]
nereus config set auto_upgrade background|notify|off
nereus config set check_interval 24h
  • Output: every command with --output (-o) takes table (the default), yaml, yamlc (coloured YAML), json and jsonc (coloured JSON); the coloured forms colour even in a pipe, since the person asked for them (#409). Every -o also has the long form --output (owner, 2026-10-31). Every get, list, describe and show takes it, and every --output has -o (owner, 2026-11-16, #1734): cli/tests/test_help.py walks the command tree and fails otherwise. A get or list of an API object prints the object without managedFields; a command that shows settings or a table of its own prints its rows keyed by their headers in camelCase (REQUIRED BY is requiredBy). A command may add a form of its own that writes an export: presentation get --output html (#1703) and session get --output agent (#1718, a YAML for an agent, with a ✓ … written line on stderr when stdout is not a terminal). An export made to be redirected writes its summary line on stderr, never stdout, so the file holds only the export (owner, 2026-11-18).
  • Order: status and every list come in alphabetical order; --sort-by <path>, as kubectl's, sorts by any field of the objects (.metadata.creationTimestamp; .createdAt on status), in every form of --output; rows without the field go last, a field no row has is refused (#808). sorted_by in output.py is the one place. Over secrets it reads what the command shows, never the encrypted values. A table whose order means something keeps it (plan steps, doctor, profile describe, settings).
  • Help: every command and group takes -h as well as --help, with the same output and the same precedence over --version and --examples (#1733); the root sets both in its context_settings, and every command inherits them.
  • Examples: every command and group takes --examples (#674): each example after a # <what it does> line, as tldr prints them; a group lists every command under it, each after a ## <path> line, and nereus --examples lists the whole CLI. With --output, they come as data for agents: command and description, plus path on a group (#675). In code, examples() takes (description, command) pairs, and cli/tests/test_help.py requires a description for each.
  • Help: flat, Click's plain text, no Rich markup or colours (TYPER_USE_RICH=0, set in cli/src/nereus/__init__.py, #704). nereus --help lists its commands in sections Platform, Session, Model and Reefs, each sorted by name, one line per command; a new top-level command sets short_help (at most 60 characters) and rich_help_panel (one of those four), and cli/tests/test_help.py requires both.
  • Flags: --param <key>=<value> for every parameter (never --set); --reef and --nereid everywhere (never --implements), never prepositions (--on-reef, --to-nereid); examples use long-form options, one per line.
  • Verbs: kubectl's, ADR 0013 (command conventions): create builds from flags and fails when the thing exists, apply creates or updates from files or folders of .yaml only (every former add), delete deletes, plus get and list; every noun takes all five, and every command that changes something takes --dry-run. add and remove are not verbs. Installing a reef or a Nereid by name (nereus nereid apply <nereid>) keeps today's form until #487 (the verb that installs a reef or a Nereid by name) decides it.
  • Output lines name the object by its full path, as Azure's resource ids do: the reef, then each kind in the plural and its name, parents before children, the platform's kinds under core, and end in created, configured, unchanged or deleted:

    secrets/vaults/default/secrets/google-oauth created (key SHA256:Xy3…)
    release/releases/keycloak created
    core/mandates/default unchanged (reef: secrets, nereid: openbao, default)
    
  • Delete waits, as kubectl's does (#526): an object whose Nereid keeps its cleanup finalizer (#525) stays until the Nereid removed what it made; meanwhile list and get show Terminating in the state column (computed by the CLI from metadata.deletionTimestamp, never written in status, ADR 0005; the --output forms carry the object as it is). delete waits until the object is gone, printing each step of status.steps as it changes (the time it changed, ✓ Done, … InProgress, · Pending, ✗ Failed, its name, its message), then the deleted line; a step Failed or Ready=False with reason: CleanupFailed ends it with exit 1 and Next steps: naming get. --wait=false (kubectl's spelling: --wait takes true or false) returns at once with <path> is Terminating: <nereid> removes what it made.; --timeout (seconds, as get --watch's) ends the wait with a failure naming the step in progress, the object left as it is. get --watch prints the steps too, and stops once a Terminating object is gone. The shared part lives in cli/src/nereus/reefkinds.py, for every reef's commands.

  • What a delete must respect lives behind the API (#874): the vcluster Nereid holds an Environment's finalizer while a Target names it and says why in the status, for any client; nereus environment delete checks first only to refuse early, and refuses when it cannot check.
  • Next steps: every output ends with a Next steps: label, a blank line before and after it, and the command indented two spaces:

    core/reefs/secrets created (secrets.getnereus.dev/v1alpha1: secrets, secretbindings, vaults)
    
    Next steps:
    
      nereus nereid apply --help
    

Kinds

The platform's own kinds are Reef, Nereid and Mandate, in core.getnereus.dev/v1alpha1, owned by the core reef (ADR 0002, ADR 0009); a reef's own kinds live in <reef>.getnereus.dev/v1alpha1. Today's code applies these kinds in these groups (#20, #402): the cloud reef ships only its Cloud kind, and its Nereid's binding is a Mandate.

Their fields:

Kind Field Holds
Reef spec the contract: API group, version, commands
Nereid spec.reefs the reefs it looks after (a list)
Nereid spec.image the image it runs, pinned by digest
Nereid spec.params its authentication and default target parameters
Mandate spec.reef, spec.nereid the reef and the Nereid it binds
Mandate spec.params the overrides of the Nereid's target parameters
Mandate spec.default true for the reef's default Mandate

A reef's own objects key their entries by reef, never by Nereid: a Cloud access entry is {reef: secrets, ...}. Today's code uses reef: in those entries and spec.reefs (a list) on Nereid.

Listing

$ nereus status
REEF            NEREID           VERSION  STATUS  AGE
core            built-in         0.1.0    Ready   38m
secrets         azure-key-vault  0.1.0    Ready   8m

$ nereus nereid list
NEREID           REEFS    IMAGE                                                              STATUS  AGE
azure-key-vault  secrets  ghcr.io/getnereus/nereus/secrets-azure-key-vault-controller:0.1.0  Ready   8m

nereus status has one row per reef and Nereid pair; nereus nereid list one row per Nereid, its reefs comma-separated (ADR 0011). nereus nereid get <nereid> shows one Nereid in full, with the image's OCI labels org.opencontainers.image.title and org.opencontainers.image.description and its digest, which nereid list leaves out.

STATUS is computed by the CLI, not written by the Nereid (spec 0003, layer 2, #527): the Nereid's own Ready condition, unless its Controller has no pod serving (Unavailable, which wins) or it does not honour its reefs' kinds (NotConformant): a reef that exposes no kind has no Ready Nereid, unless it has none by design (authentication, portal and metrics, pinned in contracts.REEFS_WITHOUT_KINDS, #794), and a Nereid serves every kind its reef exposes, declared in its status.kinds as <plural>.<group>.

core is built in and always Ready; a reef with no Nereid is Waiting, unless it needs none by design: every CRD of the reef annotated core.getnereus.dev/nereid: "none" (the tenancy reef, whose objects the API keeps, ADR 0015; #651) makes its row Ready with - as its Nereid, and its reason says why.

nereus nereid get prints why on a Reason line, nereus status --output json|yaml as the reason field of each row, and a command to a NotConformant Nereid is refused with that reason.

Secrets are encrypted on the client

A mandatory capability of the secrets reef contract: every secrets Nereid publishes a public key for each Mandate naming it, in the Mandate's status.publicKey, and decrypts inside its own boundary. The CLI encrypts each secret locally with envelope encryption: an AES-256-GCM data key encrypts the value, and the Mandate's RSA-OAEP-256 public key wraps the data key.

nereus secrets create uses the key of the Mandate it targets, the default one unless a Mandate is named. The CLI stays provider-agnostic; only the Nereid differs:

Where The private key
Azure (--target azure) A non-exportable RSA key in Key Vault; the Nereid calls Key Vault to decrypt.
Local k3d, no target A non-exportable RSA key of the OpenBao Transit engine (API: exportable defaults to false); the Nereid calls Transit to decrypt.
Fallback Sealed Secrets style: the private key in a cluster Secret.

Log redaction stays, whatever the encryption.

Through the Nereus API (#1323), the CLI still seals each value on the machine: the API stores the envelopes as they come, never returns spec.data in an answer or an error, and logs the route and the person, never a body. It hands the CLI the Mandate's public key, which the CLI checks (fingerprint, size) as it did from the apiserver.

Legacy commands

The aliases of nereus system that #409 kept for the legacy commands are gone (#410): only nereus system access list|approve stays, until its form is designed.

Legacy (platform ...) New form
platform init [--yes] nereus init
platform init --target azure nereus init --target azure (it also adds the secrets reef with Azure Key Vault, its default default Mandate, its RSA key and the vault default, ADR 0003)
platform system interface, install, uninstall, implementation nereus reef ..., nereus nereid apply, delete, list, nereus mandate create ... --default; the aliases went in #410
platform controller list, platform controller install nereus nereid list, nereus nereid apply
platform system access list, approve No new form yet (open, designed later)
platform config installation set, show No new form yet (open, designed later)
platform config slo set, show, reset No new form yet (open, designed later)
platform release ..., platform helm repo ..., platform namespace ..., platform cloud ... The reef's own commands: nereus <reef> <verb>
platform login, platform user ... Old form, no new form: users come through SSO (authentication reef); nereus user commands will be designed when Nereus needs them
none nereus status, nereus doctor, nereus nereid suggest, nereus mandate create (new)

First implementation step

Before any command of this design is built, the code's binary platform became nereus and the MCP server's name platform-mcp became nereus-mcp (#396; the names live in cli/src/nereus/names.py and one build setting, docs/agent/rules.md), so the legacy commands now run as nereus system ..., nereus config .... The sequence after that:

  • The kinds Interface, Implementation and the per-reef classes (CloudClass) became Reef, Nereid and Mandate in core.getnereus.dev/v1alpha1 (#402).
  • nereus init with no target came with the secrets reef, the openbao Nereid, the default vault Mandate and its public key (#404).
  • nereus nereid apply keycloak --reef authentication (then a legacy alias under system) added the authentication reef's local Nereid, the authorization server of the claude.ai connector (#407).
  • nereus reef create|apply|list|delete, nereus nereid apply|list|get|delete, nereus mandate create|apply|list and nereus status came, with nereus status --output json as the contract of the first MCP tool, status, served today by the Nereus API's /mcp (#409, ADR 0029).
  • nereus reef get, nereus nereid create, nereus mandate get and nereus mandate delete completed the five verbs, and the legacy aliases of nereus system went (#410).