CLI Reference

Complete reference for all Agentmd CLI commands, options, and examples.

Command Overview

Command	Description	Use Case
`agentmd new <name>`	Scaffold a new agent	Create agents via AI or interactive questionnaire (`<name>` becomes the filename / id)
`agentmd start`	Start runtime with scheduler + watcher	Long-running process for scheduled agents
`agentmd run [agent]`	Execute single agent (one-shot)	Manual execution by id (filename stem)
`agentmd chat [agent]`	Interactive chat session	Multi-turn conversation with an agent
`agentmd list`	List all agents in workspace	Shows Id and Display Name columns
`agentmd logs <agent>`	View execution history	Debug failures, review outputs (by id)
`agentmd pending`	List executions awaiting a response	Find paused (HILT) executions
`agentmd respond <id>`	Answer a waiting execution	Approve/deny or provide input
`agentmd checkpoint`	Inspect / purge checkpoint storage	Manage `agentmd_checkpoints.db`
`agentmd validate [agent]`	Validate agent configuration	Pre-deployment checks, CI/CD (by id)
`agentmd status`	Check if runtime is running	Monitor daemon state
`agentmd stop`	Stop background runtime	Gracefully stop daemon
`agentmd info`	Show effective configuration	Verify paths, API keys, defaults
`agentmd setup`	Interactive setup wizard	First-time setup or reconfiguration
`agentmd update`	Update to latest version	Self-update via uv or pip

Global Options

These options are available for all commands via the app callback:

Option	Short	Description
`--quiet`	`-q`	Print only the final answer (on `run`)
`--verbose`	`-v`	Show debug output

# Any command can use global options
agentmd -v list
agentmd -q run hello-world

agentmd new

Scaffold a new agent definition file.

Purpose

Creates a new agent .md file in the workspace. Two modes:

AI-assisted (default, when a provider + API key are configured): asks what the agent should do, then uses the configured LLM to generate the complete agent file (frontmatter + system prompt)
Interactive questionnaire (no provider configured, or --template flag): walks you through each field — description, provider, model, trigger, paths, and system prompt

If AI generation fails, it automatically falls back to the interactive questionnaire.

Usage

agentmd new <AGENT_NAME> [OPTIONS]

Arguments

Argument	Type	Description
`AGENT_NAME`	String (required)	Filename stem / id for the new agent (alphanumeric, hyphens, underscores, spaces)

Options

Option	Short	Type	Default	Description
`--workspace PATH`	`-w`	Path	from config.yaml	Override workspace directory
`--template`	`-t`	Flag	false	Skip AI, use interactive questionnaire

Examples

# AI-assisted (prompts for description, generates via LLM)
agentmd new daily-report

# Interactive questionnaire (no AI)
agentmd new daily-report --template

# Custom workspace
agentmd new my-agent -w /data/agents

Interactive Questionnaire Fields

When using --template or without an AI provider configured, the command asks:

Field	Example	Required
Description	"Summarizes daily logs"	No
Provider	google, openai, anthropic, ollama, local	No (uses default)
Model name	gemini-2.5-flash, gpt-4o	No (uses default)
Trigger	manual, schedule, watch	No (defaults to manual)
Schedule/paths	30m, `0 9 * * *`, data/uploads/	Only for schedule/watch
Read paths	logs/, data/input.csv	No
Write paths	output/, reports/	No
System prompt	"Read all logs and summarize..."	Yes

agentmd start

Start the Agentmd runtime with scheduler and file watcher.

Purpose

Launches a process that: 1. Loads all agents from the workspace 2. Starts the scheduler for agents with schedule triggers (cron, interval) 3. Starts the file watcher for agents with watch triggers 4. Displays a summary of all loaded agents 5. Runs until interrupted (Ctrl+C) or stopped via agentmd stop

Usage

agentmd start [OPTIONS]

Options

Option	Short	Type	Default	Description
`--workspace PATH`	`-w`	Path	from config.yaml	Override workspace directory
`--daemon`	`-d`	Flag	false	Run in background
`--keep-alive`		Flag	false	Never shut down on idle (server mode)
`--port INT`		Integer	none	Also listen on TCP; requires `--api-key`
`--host TEXT`		String	`127.0.0.1`	Interface for `--port`
`--api-key TEXT`		String	none	Key required on TCP requests (`X-API-Key`)
`--quiet`	`-q`	Flag	false	Suppress output except errors

Examples

# Start in foreground (default)
agentmd start

# Start as background daemon
agentmd start -d

# Start with custom workspace
agentmd start --workspace /data/agents

# Start daemon with custom workspace
agentmd start -d -w /data/agents

# Serve other machines over TCP, authenticated, never idling out
agentmd start --keep-alive --host 0.0.0.0 --port 4100 --api-key "$AGENTMD_KEY"

Daemon Mode

When started with --daemon / -d: - Runs as a detached background process - Logs output to ~/.local/state/agentmd/backend.log (rotated at 5 MB) - PID stored in ~/.local/state/agentmd/backend.pid - Server flags (--keep-alive, --port, --host, --api-key) are passed through to the detached process - Use agentmd status to check and agentmd stop to stop

Server Mode

By default the backend is a personal, on-demand process: the CLI starts it, it listens on a Unix socket at ~/.local/state/agentmd/agentmd.sock (mode 600), and it shuts itself down after 5 minutes with nothing to do — no scheduled agent, no running execution, no open stream.

Three options turn it into a service:

Option	What it changes
`--keep-alive`	Disables the idle shutdown entirely. The process runs until `agentmd stop`, `POST /shutdown`, or a signal. Use it for a supervised process (systemd, launchd, a container) and for any workspace whose agents are all `manual` — those have no scheduled job to keep it alive.
`--port`	Adds a TCP listener alongside the socket, so processes that are not the local CLI can reach the API.
`--api-key`	The key TCP callers must send as `X-API-Key`.

--port requires --api-key. Without it, agentmd start refuses to boot: the API can execute arbitrary agents (POST /agents/{id}/run), and a TCP listener is reachable by anything that can route to the host. There is no "unauthenticated port" mode.

Authentication is per transport:

Transport	Auth	Why
Unix socket	none	The socket file is `chmod 600` — the OS already restricts it to your user. The local CLI sends no key.
TCP (`--port`)	`X-API-Key` on every route except `/health`	Reachable off-box.

Both listeners serve the same runtime, so agentmd list, agentmd run and the rest keep working locally, without a key, while the port stays authenticated. --api-key alone (no --port) changes nothing and warns as much.

--host defaults to 127.0.0.1. Setting 0.0.0.0 publishes the port on every interface — do that only behind a firewall or a reverse proxy that terminates TLS, since the API key travels in cleartext over plain HTTP.

In service mode (--port or --keep-alive) an execution parked in waiting — a human-in-the-loop prompt — also holds the backend up, so a remote caller can still answer it. On the plain local socket it does not: a forgotten HILT would otherwise make the backend immortal, and agentmd respond restarts the backend and resumes the execution on demand.

agentmd run [agent]

Execute a single agent manually (one-shot execution).

Usage

agentmd run [AGENT] [OPTIONS]

Arguments

Argument	Type	Description
`[AGENT]`	String (optional)	Agent id (filename stem). If omitted, shows an interactive picker

Options

Option	Short	Type	Default	Description
`--workspace PATH`	`-w`	Path	from config.yaml	Override workspace directory
`--quiet`	`-q`	Flag	false	Print only the final answer (no steps, no summary)
`--detach`	`-d`	Flag	false	Run in the background and return immediately

Examples

# Run agent by id (filename stem)
agentmd run my-agent

# Interactive picker (when no id given)
agentmd run

# Quiet mode (final answer only — pipe-friendly)
agentmd run my-agent --quiet

# Background mode (returns immediately; check progress with `agentmd logs`)
agentmd run my-agent --detach

Event Icons

Icon	Type	Description
🤖	AI message	LLM reasoning or response
🔧	Tool call	Tool invocation with arguments
📎	Tool response	Tool execution result
✅	Final answer	Agent's final output

Human-in-the-Loop prompts

If the agent calls a guarded tool (e.g. file_delete, file_write) or ask_user, agentmd run pauses and prompts you inline for a confirmation, free-text answer, or choice, then resumes. If you are not watching the terminal, the execution enters waiting state and can be answered later with agentmd respond. With --detach, the run never prompts inline — any request goes straight to waiting and shows up in agentmd pending. See Human-in-the-Loop.

agentmd chat [agent]

Start an interactive multi-turn chat session with an agent.

Purpose

Unlike agentmd run (one-shot), agentmd chat opens a REPL where you type messages and the agent responds in real-time. Each turn is a normal agent execution, and the CLI accumulates the displayed token, cost, and duration totals for the interactive session.

When history is enabled, each new turn seeds its context from the most recent finished execution for that agent. This also means scheduled/manual runs of the same agent can contribute context; use history: off for isolated one-shot runs.

Usage

agentmd chat [AGENT] [OPTIONS]

Arguments

Argument	Type	Description
`[AGENT]`	String (optional)	Agent id (filename stem). If omitted, shows an interactive picker

Options

Option	Short	Type	Default	Description
`--workspace PATH`	`-w`	Path	from config.yaml	Override workspace directory

Examples

# Chat with an agent by id
agentmd chat my-agent

# Interactive picker (when no id given)
agentmd chat

# Custom workspace
agentmd chat my-agent -w /data/agents

Session Controls

Input	Action
`/exit` or `/quit`	End session gracefully
`Ctrl+C`	End session gracefully
`Ctrl+D` (EOF)	End session gracefully
Empty input	Ignored (re-prompts)

Like agentmd run, a chat session also prompts inline for Human-in-the-Loop requests: when a guarded tool or ask_user fires mid-turn, you answer in the terminal and the agent continues.

Example Session

  Chat with hello-world
    google / gemini-2.5-flash
    Type /exit or Ctrl+C to end session

  > What files are in the output directory?
  11:33:01  🔧 file_read → {'path': '.'}
  11:33:01  📎 file_read ← greeting.txt, report.txt
  11:33:02  ✅ The output directory contains: greeting.txt and report.txt

  > Read greeting.txt and translate it to Spanish
  11:33:10  🔧 file_read → {'path': 'greeting.txt'}
  11:33:11  🤖 Here's the translation...
  11:33:11  ✅ ¡Hola! Que tu día esté lleno de alegría...

  > /exit

  Session ended: 2 turns, 450 tokens (120 in / 330 out), 15.2s
  Execution #42

Viewing Chat History

Chat turns appear in agentmd logs like any other execution:

agentmd logs my-agent       # Shows the individual turns
agentmd logs -e 42          # View the full message history of one turn

agentmd list

List all agents in the workspace with their trigger, last run, and status.

Usage

agentmd list [OPTIONS]

Options

Option	Short	Type	Default	Description
`--workspace PATH`	`-w`	Path	from config.yaml	Override workspace directory

Table Columns

Column	Example
Id	`pesquisador` (filename stem)
Display Name	`Research Bot` or `—` when equal to id
Trigger	`cron (0 9 * * *)`, `every 1h`, `manual`
Last Run	`2h ago`, `never`
Status	`●` (enabled) / `○` (disabled)

agentmd logs

View execution history and detailed messages for an agent.

Usage

agentmd logs <AGENT> [OPTIONS]
agentmd logs -e <ID> [OPTIONS]
agentmd logs -f [OPTIONS]

Arguments & Options

Item	Type	Default	Description
`<AGENT>`	String	—	Agent id / filename stem (required for execution list)
`-n` / `--last NUM`	Integer	10	Number of recent executions
`-e` / `--execution ID`	Integer	—	Show messages for specific execution ID
`-f` / `--follow`	Flag	false	Follow daemon log output in real-time
`--workspace PATH`	Path	from config.yaml	Override workspace directory

Examples

# Show last 10 executions
agentmd logs my-agent

# Show last 5 executions
agentmd logs my-agent -n 5

# View detailed messages for execution #42
agentmd logs -e 42

# Follow daemon logs (like tail -f)
agentmd logs -f

agentmd pending

List executions that are paused, waiting for a Human-in-the-Loop response.

Usage

agentmd pending [OPTIONS]

Options

Option	Short	Type	Default	Description
`--workspace PATH`	`-w`	Path	from config.yaml	Override workspace directory

Example output

 #   Agent      Question
 ──────────────────────────────────────────────────────────────
 42  cleaner    Confirm file_delete {"path": "output/stale.log"}
 51  reporter   Enter the report title:

Use the execution # with agentmd respond to answer. See Human-in-the-Loop.

agentmd respond

Answer a waiting execution. Resumes the run automatically once answered.

Usage

agentmd respond <EXECUTION_ID> [OPTIONS]

Arguments

Argument	Type	Description
`EXECUTION_ID`	Integer (required)	The waiting execution's id (from `agentmd pending`)

Options

Option	Type	Description
`--yes`	Flag	Approve a `confirm` request
`--no`	Flag	Deny a `confirm` request
`--reason TEXT`	String	Optional reason to attach to `--yes`/`--no`
`--text TEXT`	String	Answer for an `input` request
`--choice VALUE`	String	Selected option for a `choice` request
`--workspace PATH`	Path	Override workspace directory

With no response flags, the command prompts interactively based on the pending request kind.

Examples

# Interactive (prompts for the response)
agentmd respond 42

# Approve / deny a confirmation
agentmd respond 42 --yes
agentmd respond 42 --no --reason "file is still needed"

# Provide text for an input request
agentmd respond 51 --text "Monthly Summary"

# Select a choice
agentmd respond 55 --choice staging

agentmd checkpoint

Inspect or purge the LangGraph checkpoint database (agentmd_checkpoints.db). The checkpointer is always on (it is the durability substrate for Human-in-the-Loop and history seeding), so it grows one thread per execution. A retention sweep runs automatically on startup (defaults.checkpoint_retention_days, default 30); this command is for manual inspection and cleanup.

Usage

agentmd checkpoint [OPTIONS]

Options

Option	Type	Description
`--stats`	Flag	Show DB size and thread count, grouped per agent (default when no flag given)
`--purge`	Flag	Delete eligible checkpoint threads
`--agent NAME`	String	Limit `--purge` to a single agent
`--force`	Flag	Ignore the keep-set (also removes latest-per-agent and `waiting` threads)

Keep-set

--purge (without --force) always preserves:

the latest execution per agent (needed to seed history on the next run), and
any waiting execution (needed to resume a paused run).

--force is the explicit "wipe everything" escape hatch.

Examples

# Size + thread count per agent
agentmd checkpoint --stats

# Delete eligible old threads (respects the keep-set)
agentmd checkpoint --purge

# Purge for one agent only
agentmd checkpoint --purge --agent cleaner

# Wipe everything, including latest/waiting threads
agentmd checkpoint --purge --force

agentmd validate [agent]

Validate an agent configuration without executing it.

Usage

agentmd validate [AGENT] [OPTIONS]

Arguments & Options

Item	Type	Description
`[AGENT]`	String (optional)	Agent id or path to `.md`. Interactive picker if omitted
`--workspace PATH`	Path	Override workspace directory

What it checks

Model provider and API key availability
History level (session memory configuration)
Trigger configuration (cron syntax, watch paths)
System prompt presence
Built-in and custom tool availability (including loadability)
MCP server configuration
Read/write path existence

Examples

# Validate by id
agentmd validate my-agent

# Interactive picker
agentmd validate

# Validate all agents
for agent in $(agentmd list --quiet 2>/dev/null); do
  agentmd validate "$agent"
done

agentmd status

Check if the background runtime is running.

Usage

agentmd status [OPTIONS]

Options

Option	Short	Type	Default	Description
`--workspace PATH`	`-w`	Path	from config.yaml	Override workspace directory

Example output

  agentmd is running (pid 12345)

  Uptime         2h 30m
  Workspace      /home/user/agentmd
  Log file       /home/user/agentmd/data/agentmd.log
  Started        2026-03-13 09:00:00

agentmd stop

Stop the background runtime, and confirm the process actually exited.

Usage

agentmd stop [OPTIONS]

Options

Option	Short	Type	Default	Description
`--workspace PATH`	`-w`	Path	from config.yaml	Override workspace directory
`--timeout SECONDS`		Float	15	Wait for a graceful exit before escalating

What it does

Reads the backend's PID from /info before asking it to stop — once shutdown begins the socket is closed and unlinked, so nothing on the socket can tell you whether the process is still there.
Sends POST /shutdown and waits up to --timeout for the process to exit.
If it is still alive: SIGTERM, then 5 more seconds.
If it is still alive: SIGKILL, then 3 more seconds.
Exits non-zero, loudly, if the process survived all of that — or if the PID could not be determined and the exit therefore could not be confirmed.

stop never reports success for a backend that is still running. That matters beyond tidiness: a backend that has dropped its socket but not exited still holds the scheduler, so a start issued after a falsely-successful stop spawns a second one and every trigger: schedule agent fires twice.

The default 15 s covers the whole orderly path — the connection drain plus lifespan shutdown, whose slowest step is the file watcher's 5 s join — so a backend that was about to exit cleanly is not signalled out from under itself. A healthy backend exits in well under a second and stop returns immediately.

agentmd info

Show the current effective configuration.

Usage

agentmd info

Displays: - Config file — path to config.yaml being used - Env file — path to .env being used - Workspace — resolved workspace path - Default model — provider and model used when agents omit model: - API keys — which providers have keys configured

Example output

  agentmd v0.2.3

╭─────────────── Agentmd Configuration ───────────────╮
│   Config file      ~/.config/agentmd/config.yaml     │
│   Env file         /home/user/agentmd/.env           │
│   Workspace        /home/user/agentmd                │
│   Default model    google / gemini-2.5-flash         │
│   API keys         google                            │
╰──────────────────────────────────────────────────────╯

agentmd setup

Interactive setup wizard for first-time configuration or reconfiguration.

Usage

agentmd setup [OPTIONS]

What it does

Detects existing config — asks if you want to reconfigure
Asks for workspace directory (default: ~/agentmd)
Asks for LLM provider and model
Asks for API key (masked input; skipped for ollama)
Asks for execution defaults (temperature, max_tokens, timeout, limits, history)
Creates workspace structure (agents/, agents/_config/tools/, agents/_config/skills/)
Writes ~/.config/agentmd/config.yaml
Writes .env to agents/_config/.env and ~/.config/agentmd/.env
Creates sample hello-world agent

Examples

agentmd setup

agentmd update

Update Agentmd to the latest version.

Usage

agentmd update

Tries uv tool upgrade first, falls back to pip install --upgrade. Shows current version before updating.

Configuration Files

Agentmd uses two configuration files:

`config.yaml` — Application settings

Located at ~/.config/agentmd/config.yaml (XDG standard). Auto-created with defaults on first run.

workspace: ~/agentmd
agents_dir: agents          # relative to workspace

defaults:
  provider: google
  model: gemini-2.5-flash

`.env` — API keys

Located in your workspace directory (~/agentmd/.env). Contains only API keys (secrets).

GOOGLE_API_KEY=AIza...
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

How config is found

config.yaml: ~/.config/agentmd/config.yaml (auto-created if missing)

.env: workspace .env (~/agentmd/.env)

Precedence (highest to lowest)

CLI flags (--workspace)
config.yaml values
Built-in defaults

Environment Variables

Variable	Purpose
`GOOGLE_API_KEY`	Google AI (Gemini) API key
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic (Claude) API key

Workspace Structure

~/.config/agentmd/
└── config.yaml             # Application settings (auto-created)

~/agentmd/
├── .env                    # API keys (secrets)
├── agents/                 # Agent .md files
│   ├── hello-world.md
│   ├── hello-world.memory.md  # Long-term memory keyed by id (auto-created)
│   ├── mcp-servers.json    # MCP servers config (optional)
│   └── tools/              # Custom tools (Python modules)
└── data/
    ├── agentmd.db          # Execution history (auto-created)
    ├── agentmd_checkpoints.db  # Session history checkpoints (auto-created)
    ├── agentmd.pid         # Daemon PID file (when running as daemon)
    └── agentmd.log         # Daemon log file (when running as daemon)

CLI Reference

Command Overview

Global Options

agentmd new

Purpose

Usage

Arguments

Options

Examples

Interactive Questionnaire Fields

agentmd start

Purpose

Usage

Options

Examples

Daemon Mode

Server Mode

agentmd run [agent]

Usage

Arguments

Options

Examples

Event Icons

Human-in-the-Loop prompts

agentmd chat [agent]

Purpose

Usage

Arguments

Options

Examples

Session Controls

Example Session

Viewing Chat History

agentmd list

Usage

Options

Table Columns

agentmd logs

Usage

Arguments & Options

Examples

agentmd pending

Usage

Options

Example output

agentmd respond

Usage

Arguments

Options

Examples

agentmd checkpoint

Usage

Options

Keep-set

Examples

agentmd validate [agent]

Usage

Arguments & Options

What it checks

Examples

agentmd status

Usage

Options

Example output

agentmd stop

Usage

Options

What it does

agentmd info

Usage

Example output

agentmd setup

Usage

What it does

Examples

agentmd update

Usage

Configuration Files

config.yaml — Application settings

.env — API keys

`config.yaml` — Application settings

`.env` — API keys