Quick Start

Meriadoc is a task runner for both humans and AI agents. You define tasks, jobs, and shell environments in a YAML file that lives in your project, then run them from anywhere on your machine.

Installation

Homebrew (macOS)

brew tap meriadoc-dev/meriadoc
brew install meriadoc

One-line install script (macOS and Linux)

curl -fsSL https://raw.githubusercontent.com/meriadoc-dev/meriadoc/main/install.sh | sh

Cargo

cargo install meriadoc

Prebuilt binaries for Linux (gnu, musl), macOS (arm64, x86_64), and Windows are available on GitHub Releases.

Create a spec file

Create meriadoc.yaml in your project root:

version: v1

tasks:
  build:
    description: "Build the project"
    cmds:
      - cargo build --release

  test:
    description: "Run tests"
    cmds:
      - cargo test

  deploy:
    description: "Deploy to an environment"
    agent:
      risk_level: high
      confirmation: "This will deploy to production. Continue?"
    cmds:
      - ./deploy.sh
    env:
      ENVIRONMENT:
        type: choice
        options: [dev, staging, prod]
        default: dev

jobs:
  ci:
    description: "Full CI pipeline"
    tasks:
      - build
      - test

shells:
  dev:
    description: "Development environment"
    env:
      RUST_LOG:
        type: string
        default: debug

Register your project

meriadoc config add /path/to/your/project

Meriadoc discovers spec files by walking registered directories. You can add as many project roots as you want.

Run your first task

meriadoc ls tasks              # See what's available
meriadoc run task build        # Run the build task
meriadoc run job ci            # Run the ci job
meriadoc run shell dev         # Start the dev shell

Shortcuts

Every run task, run job, and run shell has a short form:

meriadoc task build   # same as: meriadoc run task build
meriadoc t build      # even shorter

meriadoc job ci       # same as: meriadoc run job ci
meriadoc j ci

meriadoc shell dev    # same as: meriadoc run shell dev
meriadoc s dev

Web UI

Start the web server for a browser-based interface:

meriadoc server

Opens at http://localhost:8420. Browse all projects, inspect task details, run with typed inputs, and watch real-time output.

What’s next

  • Tasks — learn about env vars, preconditions, and failure handlers
  • Jobs — compose tasks into multi-step workflows
  • CLI Reference — all commands and flags
  • Agents / MCP — integrate with Claude and other AI agents