Mandrel CLI

The Mandrel CLI (mandrel-cli) is the essential toolchain for agent developers. it provides the necessary commands to validate Mandrel Specifications and generate the deployment artifacts required for the Mandrel mesh.

Installation

Automated Installer (Recommended)

Install the verified platform binary for Linux, macOS, or Windows using the official bootstrap script:

curl -sSfL https://gitlab.com/the-mandrel-project/mandrel-cli/-/raw/main/install.sh | sh

The script determines your host operating system and processor architecture, fetches the target release asset alongside checksums.txt, verifies the SHA-256 signature, and places the executable in:

• ~/.local/bin for standard user executions
• /usr/local/bin when executed under sudo

Direct Binary Download

Precompiled static binaries and SHA-256 checksums are published on GitLab Releases under explicit platform identifiers:

Always verify downloaded binaries against checksums.txt prior to execution:

sha256sum -c checksums.txt --ignore-missing

Install from Source

You can build and install directly with the Go toolchain:

go install gitlab.com/the-mandrel-project/mandrel-cli/cmd/mandrel-cli@latest

Primary Commands

1. validate

Performs deep static analysis of your agent’s specification. it checks for schema compliance, semantic consistency, and security best practices.

mandrel-cli validate agent-spec.yaml

What it checks:

• Schema validity against the Mandrel v1.0 standard.
• Required identity claims (Nested JWT/DPoP).
• Governance matrix thresholds and actions.
• Egress/Ingress network allow-lists.
• Delegation controls (max-fan-out, max-delegations).

Diagnostic codes emitted by the built-in validator:

On E030 and W030

A malformed workload reference can never match anything, so an ingress list containing one silently denies callers and an egress list containing one silently permits nothing. Neither is visible without the check, which is why it is an error rather than a warning.

W030 is a warning rather than an error because an absolute reference is legitimate — it names a workload in a foreign trust domain. But it asserts a SPIFFE federation relationship that only the platform can confirm, and it ties the spec to one deployment. Authors reach for the absolute form out of habit from when the trust domain was written into every spec, so the diagnostic suggests the path-only equivalent. See Naming a workload.

When validation detects fatal diagnostics, the command exits with code 2 (ExitValidation). Warnings do not trigger non-zero exit codes unless --strict is enabled.

When --metrology-lab <url> is provided, validate performs a live check of model-id against the lab’s ChipRateTable (GET /v1/chip-rates/models/{model-id}). Without this flag the W012 check is skipped.

2. auth

Manages credentials for the Metrology Lab.

Google IAM Authentication (Zero-Friction)

The google authentication method leverages your existing Google Cloud session (via gcloud or ADC) to provide identity tokens directly to the Metrology Lab. This removes the need for manual OAuth flows or managing your own Client IDs.

How it works:

1. Set auth_method: "google" in your config (or set MANDREL_AUTH_METHOD=google).
2. Ensure you are logged into Google: gcloud auth login.
3. The CLI will automatically call gcloud auth print-identity-token with the configured audience whenever a token is needed.

Requirements:

• The gcloud CLI must be installed and in your PATH.
• The audience in your config MUST match the expected audience of the Metrology Lab.

OIDC Authentication (Standard)

The default oidc method uses the standard OIDC Device Authorization Flow. This is suitable for non-Google providers or when gcloud is not available.

auth login

mandrel-cli auth login \
  --issuer https://accounts.google.com \
  --client-id your-google-client-id \
  --client-secret your-google-client-secret \
  --audience mandrel-metrology-lab \
  --scopes "openid profile email"

Launches the OIDC device authorization flow (RFC 8628). On success, stores the token at ~/.mandrel/credentials. All agents and platform subcommands load this token automatically.

Authentication Flags:

• --issuer: The OIDC provider URL (e.g. https://accounts.google.com).
• --client-id: (Required) The OAuth 2.0 Client ID for the device flow.
• --client-secret: (Optional) The OAuth 2.0 Client Secret, if required by your provider.
• --audience: The expected token audience for the Metrology Lab.

The MANDREL_METROLOGY_ISSUER, MANDREL_METROLOGY_CLIENT_ID, and MANDREL_METROLOGY_AUDIENCE environment variables provide defaults for these flags.

auth logout

mandrel-cli auth logout

Removes stored credentials from ~/.mandrel/credentials.

auth status

mandrel-cli auth status

Prints the current token subject, expiry, and scopes.

Configuration

The CLI supports a global configuration file at ~/.mandrel/config.yaml to store common settings and control global behavior.

Global Configuration File

# ~/.mandrel/config.yaml

# Connection settings
metrology_lab_url: "https://lab.mandrel.internal:8740"
auth_method: "google" # Options: oidc, google
issuer: "https://accounts.google.com"
client_id: "your-client-id-here"
client_secret: "your-client-secret-here"
audience: "mandrel-metrology-lab"

# Operational behavior
strict: false
allow_unclaimed_extensions: false

# Plugin management
no_plugins: false
plugins: ["plugin-a", "plugin-b"]
plugins_dirs: ["/opt/mandrel/plugins"]
ignore_plugin_failures: false
plugin_signatures: "ignore" # Options: ignore, warn, require

Configuration Precedence

The CLI resolves settings using the following precedence:

1. Command-line Flags (Highest)
2. Environment Variables
3. Configuration File
4. Defaults (Lowest)

Environment Variables

Custom Config Path

You can override the default configuration location using the --config flag on any command:

mandrel-cli --config /path/to/custom-config.yaml agents list

3. agents

Manages agent card registration and promotion with the Metrology Lab. All subcommands read the lab URL from MANDREL_METROLOGY_LAB by default; --metrology-lab <url> overrides it.

agents register

mandrel-cli agents register --file finance-agent.yaml \
                            --metrology-lab https://lab.mandrel.internal:8740

Submits the spec to the lab for registration. Re-registration overwrites the existing card; any existing Realized Spec is not automatically revoked.

agents promote

mandrel-cli agents promote finance-specialist \
                          --metrology-lab https://lab.mandrel.internal:8740

Runs the promotion gate on the registered agent. Returns the promoted MandrelSpec with a status block on success, or a rejection with L-code diagnostics on failure.

agents status

mandrel-cli agents status finance-specialist \
                         --metrology-lab https://lab.mandrel.internal:8740

Prints the current registration phase (pending, approved, rejected, or revoked) and the promotion timestamp if approved.

agents list

mandrel-cli agents list --metrology-lab https://lab.mandrel.internal:8740

Lists all registered agents visible to the caller’s token.

agents realized

mandrel-cli agents realized finance-specialist \
                           --metrology-lab https://lab.mandrel.internal:8740

Fetches the baked JSON Realized Spec for an approved agent. This is the exact artifact the Collet fetches at startup.

agents delete

mandrel-cli agents delete finance-specialist \
                          --metrology-lab https://lab.mandrel.internal:8740

Removes the agent registration and marks any existing Realized Spec as revoked.

4. platform

Administers platform-wide governance and reference data. Requires mandrel:lab:admin scope.

platform policy get

mandrel-cli platform policy get > policy.yaml

Fetches the active MandrelPlatformPolicy.

platform policy put

mandrel-cli platform policy put policy.yaml

Atomically replaces the platform policy. This affects all subsequent agents promote calls.

platform chip-rates get

mandrel-cli platform chip-rates get > rates.yaml

Fetches the active MandrelChipRateTable.

platform chip-rates put

mandrel-cli platform chip-rates put rates.yaml

Atomically replaces the chip rate table.

5. generate

Transforms your declarative spec into production-ready infrastructure-as-code (IaC) artifacts.

# Local mode: generate from a local file
mandrel-cli generate agent-spec.yaml ./dist

# High-Assurance mode: generate from a Lab-approved Realized Spec
mandrel-cli generate --realized finance-specialist ./dist

Generated Artifacts:

• Kubernetes Manifests: Deployment and Service configurations with integrated Collet sidecar.
• NetworkPolicy: K8s-native egress controls derived from the spec’s network block.
• OPA Rego Policies: Compiled governance rules to be loaded by the Collet/OPA engine.

6. version

Displays the active CLI version, commit SHA, build timestamp, runtime platform, and supported protocol version.

# Human-readable output
mandrel-cli version

# Machine-readable JSON output
mandrel-cli version --json

7. upgrade

Downloads and installs verified releases in-place using atomic binary replacement.

# Upgrade both the CLI and all registered plugins
mandrel-cli upgrade

# Upgrade only the mandrel-cli binary
mandrel-cli upgrade cli

# Upgrade all registered plugins
mandrel-cli upgrade plugins

# Upgrade a specific plugin by name
mandrel-cli upgrade plugin mandrel.io/kong-generator

# Preview available upgrades without replacing binaries
mandrel-cli upgrade --dry-run

Update Alerts and Opt-Outs

The CLI checks for newer releases in a non-blocking background routine throttled to a 24-hour cache (~/.mandrel/cache/updates.json). Update notifications render only to stderr in interactive terminal sessions.

To disable automatic update checks, set the environment variable:

export MANDREL_NO_UPDATE_CHECK=1

Or configure no_update_check: true in ~/.mandrel/config.yaml.

Common Flags

Process Exit Codes

The CLI emits standardized process exit codes to allow automation scripts and CI/CD pipelines to distinguish between governance rejections and operational failures:

Pipeline Error Handling

Automated pipelines can inspect $? to branch on specific failure conditions. For example, GitLab CI pipelines running advisory spec validation can soft-fail on specification errors while continuing to fail hard on operational or infrastructure problems:

validate-mandrel-spec:
  allow_failure:
    exit_codes: [2]

Plugin Management

plugin install

Downloads and installs a governance plugin directly from a GitLab or GitHub repository.

# Install the latest release
mandrel-cli plugin install https://gitlab.com/the-mandrel-project/mandrel-plugin-kong

# Pin to a specific release tag
mandrel-cli plugin install https://gitlab.com/the-mandrel-project/mandrel-plugin-kong@v0.0.2

# Preview actions without modifying disk
mandrel-cli plugin install https://gitlab.com/the-mandrel-project/mandrel-plugin-kong --dry-run

# Install to a custom directory
mandrel-cli plugin install https://gitlab.com/the-mandrel-project/mandrel-plugin-kong --dir ./custom-plugins

Verification and Installation Pipeline:

1. Queries the remote releases API to identify platform-specific binary assets (*-(generator|validator)-*-<os>-<arch>[.exe]) and checksums.txt.
2. Downloads the binary asset and verifies its SHA-256 cryptographic digest against checksums.txt.
3. Executes a pre-flight describe handshake on the downloaded binary, validating manifest schema integrity and confirming mandrel_compat satisfies host compatibility requirements.
4. Atomically places the binary into ~/.mandrel/plugins/ (or the directory specified by --dir) using its canonical plugin executable name.

plugins list

Lists all discovered subprocess plugins with their kind, version, and path.

mandrel-cli plugins list

plugins doctor

Runs discovery and reports the health of each plugin (manifest validity, compat string, owned extensions).

mandrel-cli plugins doctor

Plugin Extensions

Plugins can attach custom configuration blocks to a Mandrel Spec under spec.extensions. Each top-level key must be claimed by a registered validator plugin; unclaimed keys block generation by default. Pass --allow-unclaimed-extensions to downgrade this to a warning.

See the Extensions Reference and the full plugin protocol for details on writing validator and generator plugins in Go or any language.

Shell Completion

The CLI provides built-in autocompletion generation for Bash, Zsh, Fish, and PowerShell. Dynamic completion resolves commands, flags, target files, and discovered plugins on the fly.

Generating Autocompletion Scripts

# Bash
mandrel-cli completion bash > ~/.local/share/bash-completion/completions/mandrel-cli

# Zsh
mandrel-cli completion zsh > ~/.local/share/zsh/site-functions/_mandrel-cli

# Fish
mandrel-cli completion fish > ~/.config/fish/completions/mandrel-cli.fish

# PowerShell
mandrel-cli completion powershell > ~/.mandrel/completions/mandrel-cli.ps1

Dynamic Plugin Completion

Dynamic completion inspects installed plugins in ~/.mandrel/plugins/ and paths specified via --plugins-dir. Pressing <TAB> suggests registered plugin names:

# Autocompletes discovered plugins (e.g. mandrel.io/kong-generator)
mandrel-cli generate agent-spec.yaml ./dist --plugin <TAB>

# Autocompletes plugins for upgrades
mandrel-cli upgrade plugin <TAB>

Automated Configuration

The bootstrap installation script (install.sh) configures completions automatically:

• Bash and Zsh: Installed to standard user or system completion directories if the shell binary is detected.
• Fish: Installed automatically if Fish is the active shell; prompts for confirmation if Fish is installed but inactive.
• PowerShell: Writes ~/.mandrel/completions/mandrel-cli.ps1 and prompts to add the source hook to your $PROFILE.

Lifecycle Workflow

graph LR
    A[Write Spec] --> B[mandrel-cli validate]
    B --> C[mandrel-cli generate]
    C --> D[Deploy to K8s]

Dependencies

• Mandrel Go SDK: The CLI utilizes the SDK for schema parsing and artifact generation logic.

Source

The CLI source code is hosted on GitLab: gitlab.com/the-mandrel-project/mandrel-cli