Why We Developed Brand-new Apidog CLI + SKILL

This is a 10-part series sharing how Apidog developed Apidog CLI, a command-line tool for API testing and API lifecycle management. Read in order or jump to any post that interests you:

We built CLI + SKILL to handle what MCP doesn't optimize for: complex workflows with validation gates and structured execution.

MCP Continues to Serve Its Purpose

Before we dive into CLI + SKILL, let's clarify: Apidog MCP is still available and maintained.

MCP provides standardized tool connections following the protocol—that's valuable for:

• Simple, well-defined operations
• Users who prefer MCP-based workflows
• Ecosystem integration with MCP-compliant clients

We didn't replace MCP. We built CLI + SKILL to complement it.

What we discovered was that MCP excels at connecting tools, but for complex R&D workflows—multi-step processes with validation, read-back, and verification—Agents benefit from executable engineering processes. That's where CLI + SKILL fits.

Think of it this way:

The Old CLI: Running Tests at the End

Apidog CLI has long been the command-line entry point for running API tests.

apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>

That foundation still matters. Teams need a reliable way to:

• Run API tests from terminal
• Generate reports in CI pipelines
• Keep quality gates inside automation workflows

But the old CLI centered mainly on test execution. It appeared near the end of the workflow:

Design → Document → Mock → Debug → Test → [CLI runs tests]

The CLI was the last step—after everything else was done.

The New Requirement: Agents Need More

API development is changing.

AI Agents are now participating in:

For these workflows, a CLI cannot only be the last step that runs existing tests.

It also needs to give Agents a stable way to:

• Read API assets (endpoints, schemas, environments)
• Create or update test assets (test cases, test scenarios)
• Validate structured changes before writing
• Write them back to the project
• Verify the result

Systematic Expansion, Not Incremental Addition

The new Apidog CLI is not just adding a few commands to the old CLI.

It's systematically introducing Apidog's core capabilities into CLI, making it a workflow layer for developers, scripts, and AI Agents.

The architectural boundaries behind have changed dramatically.

MCP VS CLI: Execution Chain Comparison

Let's compare the typical execution chains for complex workflows.

MCP Route (Good for Tool Connection)

Initialize MCP session
        ↓
Load tool list + tool descriptions
        ↓
Agent selects tool
        ↓
Search for more tools (listOpenApiEndpoints)
        ↓
Get schema (getOpenApiDetails)
        ↓
Execute HTTP call (executeOpenApi)

MCP's strength: Standardized protocol for connecting tools to Agents.

Complexity placement: Most complexity is in the model context and tool selection stage. The Agent needs to understand:

• Tool lists
• Tool descriptions
• Input schemas
• Call sequences
• Return structures

Where it works well: Simple operations with clear tool-to-task mapping.

Where it becomes challenging: Complex workflows where the Agent must orchestrate multiple tools, understand product semantics, and handle validation.

CLI + SKILL Route (Better for Complex Workflows)

SKILL judges task type
        ↓
CLI executes product-semantic commands
        ↓
cli-schema validates structure
        ↓
agentHints gives next-step suggestions
        ↓
Verify loop (get read-back or apidog run)

CLI + SKILL's strength: Distributes complexity into the engineering system.

Complexity placement:

• SKILL: Methodology and workflow guidance
• CLI: Product-semantic execution
• cli-schema: Validation before writing
• agentHints: Navigation after execution

Where it works well: Multi-step workflows, validation-heavy operations, Agent-driven testing.

The Key Difference: Where Complexity Lives

The difference between these two approaches is where complexity is placed.

In MCP, the model must carry:

• Which tool to use
• What the tool description says
• What fields are required
• What sequence to follow
• What the return structure means

This works when the task-to-tool mapping is straightforward.

In CLI + SKILL, the engineering system carries:

• What task type this is (SKILL)
• What command to execute (CLI)
• What structure is valid (cli-schema)
• What to do next (agentHints)

This works better when workflows have validation gates, read-back requirements, and verification loops.

A Typical Workflow Example

Here's a concrete example of the CLI + SKILL workflow:

# Step 1: Read facts
apidog endpoint get <endpointId> --project <projectId>

# Step 2: Validate before writing
apidog cli-schema validate test-case-create --file ./test-case-create.json

# Step 3: Execute verification
apidog run --project <projectId> --out-dir ./apidog-reports

These three commands represent three engineering actions:

Agent Path for Complex Workflows

For complex, multi-step workflows, the Agent's path benefits from CLI + SKILL structure.

MCP Path for Complex Workflows

"Select tools → Understand schemas → Orchestrate sequence → Handle errors"

The Agent:

• Selects appropriate tools from many options
• Understands tool descriptions and schemas
• Orchestrates the correct sequence
• Handles errors through retry

This can work, but requires significant model reasoning for each decision point.

CLI + SKILL Path for Complex Workflows

"Read facts → Generate changes → Validate structure → Write → Run verification"

The Agent:

• Reads existing facts first (guided by SKILL)
• Generates changes based on facts
• Validates structure locally (cli-schema)
• Writes to the project
• Runs verification (agentHints guides next step)

The engineering system handles validation, guidance, and verification—reducing model reasoning burden.

Both paths can complete the task. CLI + SKILL reduces complexity in the model context stage.

What the CLI Now Covers

With the upgrade, CLI now covers more core Apidog resources:

This changes the role of Apidog CLI.

It's not simply a way to execute tests after everything else is done.

It can now participate earlier in the development loop—where an Agent needs to:

• Understand the project
• Generate or update test assets
• Validate changes
• Run verification

The Architecture Summary

Both are available. Choose based on your task.

What's Next

Now that we've established how CLI + SKILL complements MCP, the next question is:

What's the core principle that makes CLI + SKILL effective for complex workflows?

In Part 3, The Golden Rule: CLI Produces Facts, Model Acts on Facts, we'll explore the design philosophy that guides every CLI + SKILL decision—starting with cli-schema validate, the quality gate that catches errors before they become failed writes.

Key Takeaways

• MCP continues to work—use it for simple operations and MCP ecosystem integration
• CLI + SKILL complements MCP—better for complex workflows with validation
• The key difference is where complexity lives: model context vs. engineering system
• CLI + SKILL reduces model reasoning burden through validation, guidance, verification
• CLI now covers projects, APIs, environments, test cases, scenarios, and more
• Both approaches available—choose based on task complexity

Download Apidog to design, mock, test, and document APIs in one workspace. Learn more about Apidog CLI for command-line API testing, CI automation, and AI Agent workflows.