Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

Update agent CLI docs for mixed output formats (#781)

Louis Choquelda2661b75423
diff --git a/docs/features/claude-code-skills-plugin.md b/docs/features/claude-code-skills-plugin.md
index 806b68523..5a308b730 100644
--- a/docs/features/claude-code-skills-plugin.md
+++ b/docs/features/claude-code-skills-plugin.md
@@ -9,7 +9,7 @@ Build, run, validate, and edit AI methods directly from Claude Code.
## Overview
-The **MTHDS skills plugin** for Claude Code brings the full Pipelex workflow into your AI coding assistant. Build methods from natural language, validate them, run them, and iterate through conversational slash commands. The plugin leverages the `pipelex-agent` CLI under the hood for structured JSON communication.
+The **MTHDS skills plugin** for Claude Code brings the full Pipelex workflow into your AI coding assistant. Build methods from natural language, validate them, run them, and iterate through conversational slash commands. The plugin leverages the `pipelex-agent` CLI under the hood.
Install from [mthds-ai/skills](https://github.com/mthds-ai/skills).
diff --git a/docs/features/cli.md b/docs/features/cli.md
index 5eb632e38..bdd1d5a65 100644
--- a/docs/features/cli.md
+++ b/docs/features/cli.md
@@ -41,7 +41,7 @@ Package manifest management is currently exposed through the lowercase `mthds` C
## Agent CLI
-The `pipelex-agent` CLI is a machine-first interface designed for automated environments like Claude Code skills. All output is structured JSON to stdout, with no interactive prompts or Rich formatting.
+The `pipelex-agent` CLI is a machine-first interface designed for automated environments like Claude Code skills. Output format varies by command — JSON, raw TOML, or markdown — with no interactive prompts or Rich formatting. Errors always go to stderr as JSON.
| Command | Description |
|---------|-------------|
@@ -61,5 +61,5 @@ For detailed CLI documentation, see the [CLI reference](../tools/cli/index.md).
## Related Documentation
- [CLI Reference](../tools/cli/index.md) - Runtime CLI commands
-- [Agent CLI](../tools/cli/agent-cli.md) - Machine-oriented JSON interface
+- [Agent CLI](../tools/cli/agent-cli.md) - Machine-oriented interface for AI agents
- [Package Commands](../tools/cli/pkg.md) - Current `mthds package` manifest commands
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index 6c9a38e9d..0d0ef297a 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -1,12 +1,12 @@
---
-description: "Use the pipelex-agent CLI for machine-oriented JSON output — designed for AI agents, IDE extensions, and automation toolchains."
+description: "Use the pipelex-agent CLI for machine-oriented output — designed for AI agents, IDE extensions, and automation toolchains."
---
# Agent CLI (`pipelex-agent`)
-The `pipelex-agent` CLI is a machine-oriented companion to the main `pipelex` CLI. It is designed for programmatic consumption by AI agents, IDE extensions, and other automation tools. All output is structured JSON written to stdout (success) or stderr (error), with no Rich formatting or interactive prompts.
+The `pipelex-agent` CLI is a machine-oriented companion to the main `pipelex` CLI. It is designed for programmatic consumption by AI agents, IDE extensions, and other automation tools. Output format varies by command — JSON, raw TOML, or markdown — with no Rich formatting or interactive prompts. Errors always go to stderr as JSON.
-Its structured JSON output makes it well-suited for piping into other tools (e.g., `jq`), scripting, and integration into larger workflows. It is consumed by the `mthds-agent` CLI (from the `mthds` npm package) which itself is used by Claude Code skills, the VS Code extension, and can be called directly from the command line.
+It is consumed by the `mthds-agent` CLI (from the `mthds` npm package) which itself is used by Claude Code skills, the VS Code extension, and can be called directly from the command line.
## Global Options