Command reference

`muaz`

Muaz — a modular LLM agent platform.

Running bare muaz opens the web UI in your browser (the primary surface); use muaz chat for the terminal REPL, muaz run "<prompt>" for one-shot scripted turns, or a subcommand below.

Usage: muaz [COMMAND]

Subcommands:

chat — Start an interactive chat session
run — Run one non-interactive turn and print the result (scriptable)
pipeline — Run or list multi-agent pipelines without entering the REPL
agents — Manage agents
skills — Manage Agent Skills
config — View and edit global configuration
models — Manage models: provider profiles, the default, and per-agent bindings (all in models.yaml)
auth — Store a provider profile’s API key securely (hidden prompt). Use this to authenticate before starting chat when the key isn’t set yet
mcp — Manage MCP server registrations
runtime — Manage the bundled MCP runtimes (Node.js, uv) muaz downloads on demand
plugins — Install and manage plugins (bundled agents, skills, pipelines, prompts)
doctor — Diagnose the installation: storage, config, runtimes, and MCP server health
audit — Inspect the append-only security audit log (muaz doctor names its backend)
gateway — Start the web gateway server with a browser-based UI
purge-scope — Permanently delete ALL stored data for this scope (right to be forgotten)

`muaz chat`

Start an interactive chat session

Usage: muaz chat [OPTIONS]

Options:

-a, --agent <AGENT> — Agent to load (default: value in config.yaml)
--incognito — Do not save session to disk
--session <SESSION> — Resume an existing session by ID
--remember-approvals — Persist “approve for session” grants into the session file and restore them when this session is resumed

`muaz run`

Run one non-interactive turn and print the result (scriptable)

Reads additional input from stdin when piped, e.g.: git diff | muaz run “review this change” Approval policy applies, but anything that would prompt is denied.

Usage: muaz run [OPTIONS] [PROMPT]

Arguments:

<PROMPT> — The prompt (combined with piped stdin, if any)

Options:

-a, --agent <AGENT> — Agent to use (default: value in config.yaml)
--session <SESSION> — Resume an existing session by ID (the turn is appended to it)
--output <OUTPUT> — Output format: text (final response only) or json (response, session id, usage, and tool calls)

Default value: text

Possible values:
- text: Print only the final response text
- json: Print a JSON object with text, session id, usage, and tool calls
--incognito — Do not save the session

`muaz pipeline`

Run or list multi-agent pipelines without entering the REPL

Usage: muaz pipeline <COMMAND>

Subcommands:

run — Run a pipeline with the given input
list — List available pipelines

`muaz pipeline run`

Run a pipeline with the given input

Usage: muaz pipeline run <NAME> [INPUT]

Arguments:

<NAME> — Pipeline name (file stem in ~/.muaz/plugins/local/pipelines)
<INPUT> — Input message (read from stdin when omitted and piped)

`muaz pipeline list`

List available pipelines

Usage: muaz pipeline list

`muaz agents`

Manage agents

Usage: muaz agents <COMMAND>

Subcommands:

list — List all available agents
create — Create a new agent interactively
show — Show the full config of an agent
edit — Open an agent config in $EDITOR

`muaz agents list`

List all available agents

Usage: muaz agents list

`muaz agents create`

Create a new agent interactively

Usage: muaz agents create

`muaz agents show`

Show the full config of an agent

Usage: muaz agents show <NAME>

Arguments:

<NAME> — Agent name

`muaz agents edit`

Open an agent config in $EDITOR

Usage: muaz agents edit <NAME>

Arguments:

<NAME> — Agent name

`muaz skills`

Manage Agent Skills

Usage: muaz skills <COMMAND>

Subcommands:

list — List all discovered skills
create — Create a new skill interactively
show — Show the SKILL.md of a skill
edit — Open a skill’s SKILL.md in $EDITOR

`muaz skills list`

List all discovered skills

Usage: muaz skills list

`muaz skills create`

Create a new skill interactively

Usage: muaz skills create

`muaz skills show`

Show the SKILL.md of a skill

Usage: muaz skills show <NAME>

Arguments:

<NAME> — Skill name

`muaz skills edit`

Open a skill’s SKILL.md in $EDITOR

Usage: muaz skills edit <NAME>

Arguments:

<NAME> — Skill name

`muaz config`

View and edit global configuration

Usage: muaz config [COMMAND]

Subcommands:

show — Show the current config.yaml
edit — Edit config fields interactively
validate — Check config.yaml, agents, mcp.json, and pipelines for problems

`muaz config show`

Show the current config.yaml

Usage: muaz config show

`muaz config edit`

Edit config fields interactively

Usage: muaz config edit

`muaz config validate`

Check config.yaml, agents, mcp.json, and pipelines for problems

Usage: muaz config validate

`muaz models`

Manage models: provider profiles, the default, and per-agent bindings (all in models.yaml)

Usage: muaz models [COMMAND]

Subcommands:

list — List profiles, the default, and per-agent bindings
show — Show a profile’s full config (secrets stay as ${ENV_VAR})
add — Add a provider from the built-in presets, with a guided prompt
set — Create or replace a provider profile
tune — Tune a profile’s provider settings (run with no KEY=VALUE to list them)
set-model — Change just the default model of an existing profile
remove — Remove a provider profile
default — Set the global default provider profile (use —clear to unset)
bind — Bind an agent to a profile and/or a specific model
unbind — Remove an agent’s binding (it falls back to the default)

`muaz models list`

List profiles, the default, and per-agent bindings

Usage: muaz models list

`muaz models show`

Show a profile’s full config (secrets stay as ${ENV_VAR})

Usage: muaz models show <NAME>

Arguments:

<NAME> — Profile name

`muaz models add`

Add a provider from the built-in presets, with a guided prompt

Usage: muaz models add [OPTIONS] [PRESET]

Arguments:

<PRESET> — Preset id (from muaz models add --list); prompted for if omitted

Options:

--name <NAME> — Profile name to write (defaults to the preset id)
--model <MODEL> — Model identifier (defaults to the preset’s)
--base-url <BASE_URL> — Endpoint URL (defaults to the preset’s, where it has one)
--list — Print the available presets and exit

`muaz models set`

Create or replace a provider profile

Usage: muaz models set [OPTIONS] --type <TYPE> --model <MODEL> <NAME>

Arguments:

<NAME> — Profile name

Options:

--type <TYPE> — Provider type: anthropic | openai-compatible | gemini | bedrock | ollama
--model <MODEL> — Default model identifier (required)
--base-url <BASE_URL> — Base URL (openai-compatible / ollama)
--api-key <API_KEY> — API key, literal or ${ENV_VAR} (anthropic / openai-compatible / gemini)
--region <REGION> — AWS region (bedrock)
--aws-profile <AWS_PROFILE> — AWS credentials profile (bedrock)
--timeout-secs <TIMEOUT_SECS> — Request timeout in seconds

`muaz models tune`

Tune a profile’s provider settings (run with no KEY=VALUE to list them)

Usage: muaz models tune [OPTIONS] <NAME> [KEY=VALUE]...

Arguments:

<NAME> — Profile name
<KEY=VALUE> — Setting to change, as KEY=VALUE (repeatable)

Options:

--unset <KEY> — Clear a setting back to the provider’s default (repeatable)

`muaz models set-model`

Change just the default model of an existing profile

Usage: muaz models set-model <NAME> <MODEL>

Arguments:

<NAME> — Profile name
<MODEL> — New default model identifier

`muaz models remove`

Remove a provider profile

Usage: muaz models remove <NAME>

Arguments:

<NAME> — Profile name

`muaz models default`

Set the global default provider profile (use —clear to unset)

Usage: muaz models default [OPTIONS] [PROFILE]

Arguments:

<PROFILE> — Profile name (from models.yaml)

Options:

--clear — Clear the default instead of setting it

`muaz models bind`

Bind an agent to a profile and/or a specific model

Usage: muaz models bind [OPTIONS] <AGENT>

Arguments:

<AGENT> — Agent name (or @plugin/agent)

Options:

--profile <PROFILE> — Provider profile to bind (from models.yaml)
--model <MODEL> — Model override applied on top of the resolved profile

`muaz models unbind`

Remove an agent’s binding (it falls back to the default)

Usage: muaz models unbind <AGENT>

Arguments:

<AGENT> — Agent name (or @plugin/agent)

`muaz auth`

Store a provider profile’s API key securely (hidden prompt). Use this to authenticate before starting chat when the key isn’t set yet

Usage: muaz auth [PROFILE]

Arguments:

<PROFILE> — Provider profile to authenticate (defaults to the default binding)

`muaz mcp`

Manage MCP server registrations

Usage: muaz mcp <COMMAND>

Subcommands:

install — Register an MCP server (npm package, uvx package, or HTTP URL)
add-config — Import one or more servers from a pasted/standard MCP config ({ "mcpServers": { … } }). Reads from a file, or stdin when PATH is -
list — List all registered MCP servers
remove — Remove a registered MCP server by name
reconnect — Connect to a server now and refresh the tools muaz knows it offers
connectors — Browse or search the connector catalog (built-in + registry + overlay)
add — Add a catalog connector to mcp.json by id (then connect if it’s OAuth)
connect — Authorize an OAuth MCP server in the browser and store its tokens
logout — Clear stored OAuth tokens for a server

`muaz mcp install`

Usage: muaz mcp install [OPTIONS] <SPEC> [ARGS]...

Arguments:

<SPEC> — Package name (@scope/pkg, mcp-server-*) or http(s):// URL
<ARGS> — Extra arguments passed to the server process (stdio only)

Options:

--name <NAME> — Override the derived server name
--uvx — Use uvx (uv tool run) instead of npx
--env <KEY=VALUE> — Environment variable for the server, as KEY=VALUE (repeatable). Values may be literals or ${VAR} references resolved at connect time
--header <KEY=VALUE> — HTTP header for an http server, as KEY=VALUE (repeatable). Values may be literals or ${VAR} references resolved at connect time

`muaz mcp add-config`

Import one or more servers from a pasted/standard MCP config ({ "mcpServers": { … } }). Reads from a file, or stdin when PATH is -

Usage: muaz mcp add-config <PATH>

Arguments:

<PATH> — Path to a JSON config file, or - to read from stdin

`muaz mcp list`

List all registered MCP servers

Usage: muaz mcp list

`muaz mcp remove`

Remove a registered MCP server by name

Usage: muaz mcp remove <NAME>

Arguments:

<NAME> — Logical name of the server to remove

`muaz mcp reconnect`

Connect to a server now and refresh the tools muaz knows it offers

Sessions start a server only when one of its tools is called, building the toolset from what muaz remembers — so a server that grows a new tool stays invisible until this asks it again.

Usage: muaz mcp reconnect <NAME>

Arguments:

<NAME> — Logical name of the server to re-check

`muaz mcp connectors`

Browse or search the connector catalog (built-in + registry + overlay)

Usage: muaz mcp connectors [QUERY]

Arguments:

<QUERY> — Optional search query over connector id, name, and description

`muaz mcp add`

Add a catalog connector to mcp.json by id (then connect if it’s OAuth)

Usage: muaz mcp add [OPTIONS] <CONNECTOR_ID>

Arguments:

<CONNECTOR_ID> — Connector id from muaz mcp connectors

Options:

--name <NAME> — Override the registered server name (defaults to the connector id)

`muaz mcp connect`

Authorize an OAuth MCP server in the browser and store its tokens

Usage: muaz mcp connect [OPTIONS] <NAME>

Arguments:

<NAME> — Logical name of the registered http + oauth server

Options:

--client-id <CLIENT_ID> — Pre-registered OAuth client id (required for providers without dynamic client registration, e.g. Google, Slack)
--client-secret <CLIENT_SECRET> — Pre-registered OAuth client secret, if the provider issues one

`muaz mcp logout`

Clear stored OAuth tokens for a server

Usage: muaz mcp logout <NAME>

Arguments:

<NAME> — Logical name of the server to sign out

`muaz runtime`

Manage the bundled MCP runtimes (Node.js, uv) muaz downloads on demand

Usage: muaz runtime <COMMAND>

Subcommands:

list — Show managed runtime status (installed / pinned versions)
install — Download a runtime now (node | uv; default: those your MCP servers need)
update — Re-download installed runtimes (refresh pinned versions after upgrading muaz)
clean — Remove all downloaded runtimes

`muaz runtime list`

Show managed runtime status (installed / pinned versions)

Usage: muaz runtime list

`muaz runtime install`

Download a runtime now (node | uv; default: those your MCP servers need)

Usage: muaz runtime install [NAME]

Arguments:

<NAME> — Runtime to install: node or uv (omit to install what’s needed)

`muaz runtime update`

Re-download installed runtimes (refresh pinned versions after upgrading muaz)

Usage: muaz runtime update

`muaz runtime clean`

Remove all downloaded runtimes

Usage: muaz runtime clean

`muaz plugins`

Install and manage plugins (bundled agents, skills, pipelines, prompts)

Usage: muaz plugins <COMMAND>

Subcommands:

install — Install a plugin from a local .zip path, or by name from the registry (optionally pinned as name@version)
search — Search the configured plugin registries
list — List installed plugins (enabled/disabled, trusted)
show — Show a plugin’s manifest and contents
enable — Enable a disabled plugin
disable — Disable a plugin without uninstalling it
uninstall — Uninstall a plugin (deletes its directory)
trust — Trust a plugin: honour its skill tool pre-approvals and run its hooks
untrust — Revoke trust: the plugin still works, but its tool grants prompt again
update — Check for and apply plugin updates from the registry
pack — Pack a plugin directory into the reproducible .zip a registry publishes
verify — Inspect a packed plugin .zip the way an install will: its sha256, its manifest, and its detached signature
registries — Show what muaz has recorded about each configured registry (index serial, whether it signs) — the state behind rollback protection
forget-registry — Forget a registry’s recorded index serial, so a lower one is accepted again. Only for a registry you know legitimately reset or stopped signing — it is what a rollback attack needs you to run

`muaz plugins install`

Install a plugin from a local .zip path, or by name from the registry (optionally pinned as name@version)

Usage: muaz plugins install [OPTIONS] <TARGET>

Arguments:

<TARGET> — Path to a .zip, or a registry plugin name (name or name@version)

Options:

--force — Overwrite an existing plugin with the same id
--registry <REGISTRY> — Install only from this configured registry (a name under plugin_registries)
--allow-unsigned — Install a plugin the registry serves unsigned. For developing against your own registry — the browser UI never offers this

`muaz plugins search`

Search the configured plugin registries

Usage: muaz plugins search <QUERY>

Arguments:

<QUERY> — Substring to match against plugin names and descriptions

`muaz plugins list`

List installed plugins (enabled/disabled, trusted)

Usage: muaz plugins list

`muaz plugins show`

Show a plugin’s manifest and contents

Usage: muaz plugins show <ID>

Arguments:

<ID> — Plugin id

`muaz plugins enable`

Enable a disabled plugin

Usage: muaz plugins enable <ID>

Arguments:

<ID> — Plugin id

`muaz plugins disable`

Disable a plugin without uninstalling it

Usage: muaz plugins disable <ID>

Arguments:

<ID> — Plugin id

`muaz plugins uninstall`

Uninstall a plugin (deletes its directory)

Usage: muaz plugins uninstall <ID>

Arguments:

<ID> — Plugin id

`muaz plugins trust`

Trust a plugin: honour its skill tool pre-approvals and run its hooks

Usage: muaz plugins trust <ID>

Arguments:

<ID> — Plugin id

`muaz plugins untrust`

Revoke trust: the plugin still works, but its tool grants prompt again

Usage: muaz plugins untrust <ID>

Arguments:

<ID> — Plugin id

`muaz plugins update`

Check for and apply plugin updates from the registry

Usage: muaz plugins update [OPTIONS] [ID]

Arguments:

<ID> — Plugin id to update; omit to update all with available updates

Options:

--check — Only report available updates without installing them

`muaz plugins pack`

Pack a plugin directory into the reproducible .zip a registry publishes

Usage: muaz plugins pack [OPTIONS] <DIR>

Arguments:

<DIR> — Path to the plugin directory (the one containing manifest.yaml)

Options:

-o, --out <OUT> — Output path (default: <id>-<version>.zip in the current directory)
--json — Print the archive’s metadata as JSON, for scripting an index build

`muaz plugins verify`

Inspect a packed plugin .zip the way an install will: its sha256, its manifest, and its detached signature

Usage: muaz plugins verify [OPTIONS] <ZIP>

Arguments:

<ZIP> — Path to the .zip

Options:

--sig <SIG> — Signature to check (default: <zip>.minisig when it exists)
--key <KEY> — Public key to check against: a minisign key, or a .pub file. Repeatable; defaults to the publisher keys built into muaz

`muaz plugins registries`

Show what muaz has recorded about each configured registry (index serial, whether it signs) — the state behind rollback protection

Usage: muaz plugins registries

`muaz plugins forget-registry`

Forget a registry’s recorded index serial, so a lower one is accepted again. Only for a registry you know legitimately reset or stopped signing — it is what a rollback attack needs you to run

Usage: muaz plugins forget-registry <NAME>

Arguments:

<NAME> — Registry name, as configured under plugin_registries

`muaz doctor`

Diagnose the installation: storage, config, runtimes, and MCP server health

Usage: muaz doctor

`muaz audit`

Inspect the append-only security audit log (muaz doctor names its backend)

Usage: muaz audit <COMMAND>

Subcommands:

tail — Show the most recent audit events
export — Print the entire audit log (raw JSON Lines) to stdout

`muaz audit tail`

Show the most recent audit events

Usage: muaz audit tail [OPTIONS]

Options:

-c, --count <COUNT> — How many events to show (default 20)

Default value: 20
--json — Emit raw JSON Lines instead of a formatted table

`muaz audit export`

Print the entire audit log (raw JSON Lines) to stdout

Usage: muaz audit export

`muaz gateway`

Start the web gateway server with a browser-based UI

Usage: muaz gateway [OPTIONS]

Options:

-p, --port <PORT> — Port to listen on (default: 7878)

Default value: 7878
--host <HOST> — Address to bind. Defaults to loopback (127.0.0.1); pass 0.0.0.0 to expose the agent runtime to the network (prints a warning)

Default value: 127.0.0.1
--token <TOKEN> — Shared secret required on every request. Defaults to $MUAZ_GATEWAY_TOKEN, else a freshly generated token printed at startup
--readonly — Read-only mode: serve the UI and all reads, but refuse every state-changing request (no chat turns, no config/plugin/connector edits). For auditors and demos

`muaz purge-scope`

Permanently delete ALL stored data for this scope (right to be forgotten)

Removes every object, session, and audit record for the current scope (set by MUAZ_SCOPE; local by default). Irreversible. Intended for operators answering a data-deletion request — not part of everyday use.

Usage: muaz purge-scope [OPTIONS]

Options:

--yes — Skip the confirmation prompt. Required for non-interactive use
--json — Report the counts as JSON on stdout instead of a sentence