CLI Reference

The CLI is available as both meriadoc and merry. All commands work from any directory — Meriadoc finds your projects via the configured discovery roots.

Global flags

Flag	Description
`--json`	Output as JSON (for scripts and tooling)
`--config <path>`	Use a specific config file instead of the default
`--version`	Print version and exit
`--help`	Print help

Discovery & listing

meriadoc ls                    # List all registered projects
meriadoc ls tasks              # List all tasks across all projects
meriadoc ls jobs               # List all jobs
meriadoc ls shells             # List all shells

With --json:

meriadoc --json ls tasks       # JSON array of task metadata
meriadoc --json ls projects    # JSON array of project info

Running

# Full form
meriadoc run task <name>
meriadoc run job <name>
meriadoc run shell <name>

# Shortcuts
meriadoc task <name>     # or: meriadoc t <name>
meriadoc job <name>      # or: meriadoc j <name>
meriadoc shell <name>    # or: meriadoc s <name>

Run flags

Flag	Description
`--env KEY=VALUE`	Override an env var (repeatable)
`--dry-run`	Preview without executing
`--prompt-all`	Prompt for every env var, even those with defaults
`--no-interactive` / `-n`	Fail instead of prompting for missing required vars
`--verbose`	Show extra execution detail

Examples:

meriadoc run task deploy --env ENVIRONMENT=staging
meriadoc run task deploy --dry-run
meriadoc run task deploy --env ENV=prod --env VERSION=2.0.0
meriadoc task build -n                  # fail if any required var is missing

Information

meriadoc info task <name>       # Show full task details
meriadoc info job <name>        # Show job details
meriadoc info shell <name>      # Show shell details

meriadoc --json info task <name>  # JSON output

Environment

meriadoc env show task <name>    # Show resolved env vars for a task
meriadoc env show job <name>     # Show resolved env vars for a job
meriadoc env ls                  # List saved env files

Configuration

meriadoc config add <path>       # Register a project directory
meriadoc config rm <path>        # Unregister a directory
meriadoc config ls               # List all registered directories

The global config lives at ~/.config/meriadoc/config.yaml. See Config File.

Validation

meriadoc validate                # Validate all discovered specs
meriadoc doctor                  # Diagnose common issues (config, paths, spec validity)

validate reports errors in spec files without running anything. doctor checks your overall setup — registered directories, reachable spec files, config health.

Server

meriadoc server                  # Start HTTP server + Web UI at localhost:8420
meriadoc server --port 9000      # Custom port

Provides a Web UI and REST API. See Agents / MCP for the API endpoints.

MCP (stdio)

meriadoc serve                   # Start MCP JSON-RPC server over stdio

Used for AI agent integration (Claude Desktop, etc.). See Agents / MCP.

Shell completions

meriadoc completions zsh         # Generate zsh completions
meriadoc completions bash        # Generate bash completions
meriadoc completions fish        # Generate fish completions
meriadoc completions powershell  # Generate PowerShell completions

Install for zsh:

mkdir -p ~/.zfunc
meriadoc completions zsh > ~/.zfunc/_meriadoc
# Add to ~/.zshrc if not present:
# fpath+=~/.zfunc && autoload -Uz compinit && compinit

Install for bash:

meriadoc completions bash > ~/.local/share/bash-completion/completions/meriadoc

Homebrew users get completions installed automatically.

Task name resolution

When multiple projects are registered, tasks are namespaced as project:taskname:

meriadoc run task myapp:build
meriadoc run task otherproject:deploy

If a task name is unique across all projects, you can omit the prefix:

meriadoc run task build          # works if "build" exists in only one project