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

The CLI is written in Go and can be installed directly from the source:

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

Common Flags

Plugin Management

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.

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