DEV Community: Marta Karaś

Building an AI-Agent-Friendly CLI: Lessons from deployhq-cli

Marta Karaś — Thu, 16 Apr 2026 14:10:12 +0000

Building an AI-Agent-Friendly CLI: Lessons from deployhq-cli

AI coding agents can run shell commands. That means every CLI tool you ship is potentially an agent tool -- but most CLIs are built for humans staring at a terminal, not for an LLM parsing stdout. When we built deployhq-cli, we designed it for both from day one. Here is what we learned.

Why CLIs Are Natural Agent Tools

Before reaching for SDKs, MCP servers, or custom integrations, consider what a CLI already gives you:

Structured output via --json. An agent does not need to scrape table formatting. One flag and it gets clean JSON it can parse reliably.

Exit codes. Zero means success, non-zero means failure. An agent can branch on this without parsing error messages.

Self-documenting via --help. Every subcommand describes itself. An agent can explore the tool's surface area without external docs.

Composability. Pipes, redirects, and shell scripting work the same whether a human or an agent is driving.

The gap is not capability -- it is discoverability and consistency. A human reads a README and builds a mental model. An agent needs that mental model handed to it in a format it can consume in one shot.

The SKILL.md Pattern

The single most impactful thing we did was create a SKILL.md file -- a structured markdown document that teaches any AI agent how to use the CLI.

Here is the structure:

# DeployHQ CLI -- Agent Skill Guide

## Identity
What this tool is and does, in one paragraph.

## Authentication
Three methods, checked in order: env vars, config files, interactive login.

## Output Contract
stdout is ALWAYS data. stderr is ALWAYS human messages.
--json forces JSON. Exit codes: 0 = success, non-zero = failure.

## Command Groups
Table mapping group names to descriptions and reference docs.

## Decision Trees
Step-by-step workflows for common tasks.

## Invariants
Rules that always hold true.

## Gotchas
Things that will trip up an agent if not warned about.

The decision trees are the most valuable section. Instead of making the agent figure out that deploying code requires listing projects, then listing servers, then creating a deployment, you spell it out:

### "Deploy code"
1. `dhq projects list --json` -- find project permalink
2. `dhq servers list -p <project> --json` -- find server identifier
3. `dhq deploy -p <project> -s <server> --json` -- create deployment
4. `dhq deployments watch <id> -p <project>` -- monitor progress

The gotchas section prevents the agent from learning things the hard way. For example: dhq env-vars create will prompt for a value interactively if --value is omitted. That hangs an agent. The SKILL.md warns: "always pass --value."

One file. No SDK. No API wrapper. The agent reads it, and it knows how to drive your CLI.

Design Decisions for Agent-Friendliness

Breadcrumbs in JSON Output

Every JSON response includes a breadcrumbs array with suggested next commands:

{
  "ok": true,
  "data": {
    "identifier": "abc123",
    "status": "completed"
  },
  "summary": "Deployment abc123 completed",
  "breadcrumbs": [
    {"action": "logs", "cmd": "dhq deployments logs abc123 -p my-app"},
    {"action": "rollback", "cmd": "dhq rollback abc123 -p my-app"}
  ]
}

This is the single best feature for agent workflows. The agent does not need to construct the next command from scratch -- it picks from contextually relevant suggestions. After a deployment completes, the breadcrumbs suggest checking logs or rolling back. After creating a project, they suggest connecting a repo.

Self-Discovery via `dhq commands --json`

An agent can dump the full command catalog at runtime:

dhq commands --json

This returns every command, its flags, required arguments, and descriptions. Combined with SKILL.md for workflow logic and --help for individual commands, an agent has three layers of discovery: strategic (SKILL.md), catalog (commands), and tactical (help).

Consistent Error Shapes

Every error follows the same JSON structure regardless of which command failed. The agent does not need different error-parsing logic per subcommand. Combined with non-zero exit codes, error handling is mechanical.

Non-Interactive Guarantee

The CLI never prompts when all required flags are provided. This is documented as an invariant in SKILL.md. Three commands (dhq init, dhq hello, dhq auth login) are interactive by design -- the rest are fully non-interactive when flags are supplied. An agent knows to avoid the interactive commands and supply all flags explicitly.

Stderr for Humans, Stdout for Machines

This separation means an agent can safely parse stdout as JSON without worrying about progress spinners, warnings, or decorative output contaminating the data stream. Humans still see friendly output on stderr when running interactively.

The Plugin Ecosystem

A SKILL.md file is useful, but how does an agent find it? We built multiple discovery paths:

plugin.json manifest. A .claude-plugin/plugin.json file declares the skill's name, version, description, and location:

{
  "name": "deployhq",
  "version": "1.0.0",
  "description": "Deploy code, manage servers, and automate infrastructure via the DeployHQ CLI",
  "skills": ["skills/deployhq"]
}

dhq setup claude installs the skill directly into a project's Claude Code configuration. One command and the agent has the SKILL.md in its context. Same for Codex, Cursor, and Windsurf.

Directory listings. Sites like skills.sh and claudepluginhub.com, plus GitHub topics, let users discover agent-ready CLI tools. The plugin.json manifest is what these directories index.

The goal is zero-friction adoption: a developer installs the CLI, runs dhq setup claude, and their agent can deploy code.

Real Workflow Examples

Deploy to Production

# Agent discovers available projects
dhq projects list --json

# Agent picks the right server
dhq servers list -p my-app --json

# Deploy latest code
dhq deploy -p my-app -s production --wait --json

# On success, breadcrumbs suggest: view logs, open in browser
# On failure, breadcrumbs suggest: view logs, retry, rollback

Debug a Failed Deployment

# Check recent deployments
dhq deployments list -p my-app --json

# Get details on the failed one
dhq deployments show dep-456 -p my-app --json

# Read the step logs to find the error
dhq deployments logs dep-456 -p my-app

# Roll back to the last good state
dhq rollback dep-456 -p my-app --json

Rollback Under Pressure

# One command -- rollback creates a reverse deployment
dhq rollback dep-456 -p my-app --json

# Monitor the rollback
dhq deployments watch <rollback-id> -p my-app

In each case, the agent follows the decision tree from SKILL.md, uses --json for parsing, and follows breadcrumbs for next steps. No guesswork.

How to Make YOUR CLI Agent-Friendly

Here are the concrete steps, roughly in priority order:

1. Add --json to every command. This is table stakes. If your output is only human-readable tables, agents cannot use your tool reliably. Bonus: let users select fields with --json field1,field2.

2. Separate data from decoration. Stdout should be pure data (tables or JSON). Progress bars, warnings, and color codes go to stderr. This lets agents pipe stdout safely.

3. Write a SKILL.md. One markdown file with: what the tool does, how to authenticate, what the output contract is, decision trees for common workflows, and gotchas. This is the highest-leverage documentation you can write.

4. Add breadcrumbs to JSON output. After every operation, include a breadcrumbs array with contextually relevant next commands. This turns your CLI from a bag of commands into a guided workflow.

5. Never prompt when flags are provided. If all required arguments are supplied via flags, the command should run without interaction. Document which commands are interactive and which are not.

6. Add a commands subcommand. Let agents dump your full command catalog as JSON at runtime. This is the self-discovery escape hatch.

7. Use consistent exit codes and error shapes. Zero for success, non-zero for failure. Errors should follow one JSON schema across all commands.

8. Ship a plugin manifest. A plugin.json with your tool's metadata lets agent ecosystems index and auto-discover your CLI.

None of these changes hurt the human experience. Structured output, consistent errors, and self-documentation make a CLI better for everyone. The agent-friendliness comes for free once you commit to these patterns.

The Takeaway

The best agent integration is often the simplest one. You do not need an MCP server, a custom SDK, or a SaaS integration layer. A well-structured CLI with --json output, a SKILL.md file, and breadcrumbs in responses gives any AI agent everything it needs to drive your tool competently.

Build for machines and humans at the same time. They want the same things: clear contracts, predictable behavior, and good error messages. The only difference is that machines read JSON and humans read tables.

deployhq-cli is open source under MIT. Try dhq setup claude to see the skill pattern in action.

Building a CLI for Humans and AI Agents

Marta Karaś — Fri, 03 Apr 2026 10:27:25 +0000

Most CLIs are built for humans. Some are built for scripts. We built one for both — and for AI agents too.

DeployHQ CLI (dhq) is a Go command-line tool for the DeployHQ deployment platform. It manages projects, servers, deployments, and releases. But what makes it different is that it was designed from day one to work equally well when a human is typing, when a shell script is piping, or when an AI agent is orchestrating.

Here's what that looks like in practice.

The Output Contract

The single most important design decision: stdout is always data, stderr is always human text.

# Human sees a nice table on stderr, data goes to stdout
dhq projects list

# Pipe it and get JSON automatically — no flag needed
dhq projects list | jq '.data[].name'

When stdout is a TTY, you get a formatted table. When it's piped, you get JSON. No --json flag required (though you can use it explicitly).

Field Selection with `--json`

Most CLIs give you --json and dump everything. We give you --json <fields>:

# Only get what you need
dhq deployments list -p my-app --json identifier,status,timestamps.duration

# An agent requesting just the deployment ID and status
dhq deploy -p my-app -s prod --use-latest --json identifier,status

This matters for agents because tokens cost money. A full deployment object might be 50+ fields. An agent checking status needs two.

Breadcrumbs: Teaching Agents What To Do Next

Every JSON response includes a breadcrumbs array — suggested next commands based on what just happened:

{
  "data": { "identifier": "abc123", "status": "completed" },
  "breadcrumbs": [
    "dhq deployments logs abc123 -p my-app",
    "dhq deployments show abc123 -p my-app --json"
  ]
}

An AI agent doesn't need to memorize your API. It reads the breadcrumbs and knows what's possible next. This turns a stateless CLI into a guided workflow.

Agent Detection

The CLI detects when it's being used by an agent:

export DEPLOYHQ_AGENT=1      # Explicit agent mode
export CLAUDE_CODE=1          # Auto-detected
export CI=true                # Auto-detected

In agent mode, the CLI adjusts its behavior — suppressing interactive prompts, defaulting to structured output, and including richer metadata.

JSONL Capture

Set DEPLOYHQ_OUTPUT_FILE=log.jsonl and every command's output gets appended as a JSONL line. Useful for:

Agent audit trails
CI pipeline debugging
Replaying what happened during an automated workflow

Non-Interactive Auth

Three env vars, no browser popup:

export DEPLOYHQ_ACCOUNT=myaccount
export DEPLOYHQ_EMAIL=me@example.com
export DEPLOYHQ_API_KEY=abc123

This is table stakes for CI, but it matters even more for agents. An AI agent can't click "Authorize" in a browser.

Exit Codes That Mean Something

0 — success
1 — failure (with structured error in JSON)
Empty results return 0 with empty data — that's not an error

Simple, but surprisingly rare. Many CLIs return 0 on errors or don't include error details in their JSON output.

The Go SDK Inside

The CLI wraps a public Go SDK at pkg/sdk/ with 97 methods. The SDK has zero internal imports — it's designed to be extractable as a standalone module:

client := sdk.NewClient("account", "email", "apikey")
projects, err := client.ListProjects()

If you're building Go tooling around DeployHQ, you can use the SDK directly without shelling out to the CLI.

What We Learned

Building for agents changed how we think about CLIs:

Structured output isn't optional — if your CLI can't produce JSON, agents can't use it reliably
Field selection saves tokens — agents pay per token, don't make them parse 50 fields to get 2
Breadcrumbs beat documentation — agents don't read man pages, but they read JSON responses
Non-interactive is non-negotiable — if it needs a human to click something, agents can't use it
Piped detection is free UX — detect TTY vs pipe and adjust automatically

The future of CLIs isn't human OR machine. It's both.

Links:

GitHub: https://github.com/deployhq/deployhq-cli
Install: brew install deployhq/tap/dhq
DeployHQ: https://www.deployhq.com

DEV Community: Marta Karaś

Building an AI-Agent-Friendly CLI: Lessons from deployhq-cli

Building an AI-Agent-Friendly CLI: Lessons from deployhq-cli

Why CLIs Are Natural Agent Tools

The SKILL.md Pattern

Design Decisions for Agent-Friendliness

Breadcrumbs in JSON Output

Self-Discovery via dhq commands --json

Consistent Error Shapes

Non-Interactive Guarantee

Stderr for Humans, Stdout for Machines

The Plugin Ecosystem

Real Workflow Examples

Deploy to Production

Debug a Failed Deployment

Rollback Under Pressure

How to Make YOUR CLI Agent-Friendly

The Takeaway

Building a CLI for Humans and AI Agents

The Output Contract

Field Selection with --json

Breadcrumbs: Teaching Agents What To Do Next

Agent Detection

JSONL Capture

Non-Interactive Auth

Exit Codes That Mean Something

The Go SDK Inside

What We Learned

Self-Discovery via `dhq commands --json`

Field Selection with `--json`