Apidog CLI is designed to bring Apidog's API lifecycle capabilities into AI Agent workflows. With Apidog CLI and Apidog AI Agent Skills, an AI Agent can use command-line workflows to query project resources, run automated API tests, validate data before writing, and manage API or testing assets.Apidog CLI is suitable for AI Agents because it provides stable, verifiable engineering actions instead of requiring the Agent to call many small tools one by one.What an AI Agent can do with Apidog CLI#
After Apidog CLI is installed and authenticated, an AI Agent can use it to help with tasks such as:View and manage API resources, including endpoints, schemas, folders, parameters, and response definitions.
Create and update API test cases based on API definitions.
Manage automated test scenarios and test suites.
Run automated test scenarios and test suites from the command line.
Generate test reports in formats such as CLI, HTML, and JSON.
Manage environments, variables, and runtime settings.
Import and export API data in formats such as OpenAPI, Postman, HAR, JMeter, WSDL, Markdown, and Apidog native format.
Manage API documentation sites and shared docs.
Work with branches, including AI branches for safer Agent-generated changes.
Why use Apidog CLI instead of only MCP tools?MCP tools expose many atomic API operations. Apidog CLI provides higher-level commands that align with common development workflows.Compared with MCP-only approaches, Apidog CLI helps AI Agents by providing:Higher-granularity actions, such as read → validate → write → verify.
Runtime schema validation with cli-schema validate.
Structured command output with agentHints to guide next steps.
Pre-write validation to catch errors before creating or updating resources.
Fewer repeated tool calls and lower token consumption.
Prerequisites#
Before using Apidog CLI with an AI Agent, make sure:Node.js and npm/npx are installed.
You have an Apidog account.
The account has access to the Apidog project you want the Agent to operate on.
The CLI is authenticated with an Apidog API access token.
Apidog AI Agent Skills are installed for your Agent.
Install Apidog CLI#
Install or upgrade Apidog CLI:You can also ask your AI Agent to follow the installation guide:Read https://apidog.com/apidog-cli-installation-guide.md and follow instructions.
Get an API access token#
Get an access token from the Apidog app or web console:Do not print the token in logs, chat messages, or repository files.
Log in to Apidog CLI#
Check the current login identity:List accessible projects:If you already know the project ID, verify access with a resource query command:Record a long-term working project#
For Agent workflows, it is recommended to save the commonly used project ID in .apidog/settings.json.Project → Project Settings → Basic Settings → Project ID
.apidog/settings.json:When the user request does not explicitly specify a project, the AI Agent can use the projectId saved in this file.Also make sure .apidog/.gitignore contains:Install Apidog AI Agent Skills#
Install Apidog AI Agent Skills so the Agent knows how to use Apidog CLI correctly:This command starts an interactive flow where you can choose the Skills, target AI Agent, and installation scope.You can also install from the GitHub repository:If the current environment cannot access the official installation source, manually install Apidog AI Agent Skills according to your AI Agent's rules. Use WebFetch to fetch:https://apidog.com/.well-known/agent-skills/index.json
SKILL.md files from the url fields.Installing all 8 skills is recommended. At minimum, install apidog-cli.
How Apidog AI Agent Skills help#
Apidog CLI + SKILL.md is designed for AI Agent integration. The Skills system helps Agents use the CLI correctly by providing:Task-aware invocation: Agents can match Skills to relevant tasks without repeatedly specifying CLI usage.
Judgment rules: Guidance on when to validate, when to read back, and when not to guess IDs.
Workflow guidance: Recommended next steps through agentHints in command output.
AI Branch safety: Changes can be made in isolated AI branches to avoid directly contaminating the main branch.
Use AI branches for safer Agent-generated changes#
When an AI Agent needs to modify API or testing assets, use an AI branch when possible.An AI branch helps keep Agent-generated changes isolated by:Keeping Agent modifications separate from the main branch.
Reminding users that changes have not yet been merged.
Requiring user confirmation before merge.
By default, project write permissions may be restricted for safety. To edit the main branch directly, enable external AI edit permissions in project AI Feature Settings.
Validate data before writing#
When an Agent creates or updates structured resources, use cli-schema validate before writing.This validation helps catch issues such as:Example Agent workflow#
A typical AI Agent workflow with Apidog CLI looks like this:1.
The user asks the Agent to inspect, test, or update an Apidog project.
2.
The Agent checks .apidog/settings.json or asks for the target project ID.
3.
The Agent verifies CLI login status with apidog whoami.
4.
The Agent reads project resources with CLI commands.
5.
If writing data, the Agent prepares local JSON files.
6.
The Agent validates the files with cli-schema validate.
7.
The Agent applies changes through Apidog CLI.
8.
The Agent reads back the updated resource or test result to verify the change.
9.
If changes are made in an AI branch, the user reviews and confirms before merge.
Run tests through an AI Agent#
An Agent can use Apidog CLI to run automated API tests.Best practices#
When using Apidog CLI with AI Agents:Store access tokens securely. Do not place tokens in prompts, logs, repository files, or screenshots.
Save the common project ID in .apidog/settings.json when the Agent frequently works with one project.
Use apidog whoami to verify the current login identity.
Use apidog <command> --help when command parameters are unclear.
Use cli-schema validate before creating or updating structured resources.
Prefer AI branches for Agent-generated changes.
Read back resources or test results after changes to verify the outcome.
Use CI/CD commands for repeatable automated testing workflows.
Troubleshooting#
| Issue | Solution |
|---|
apidog: command not found | Reinstall Apidog CLI globally and make sure the npm global bin directory is in PATH. |
| Not logged in | Run apidog login --with-token <TOKEN> again. |
| Project not found or permission denied | Check the project ID and make sure the token account has access to the project. |
| Unsure command parameters | Run apidog <command> --help for the latest usage. |
| Invalid characters in header content | Check environment variable initial values, authorization header values, and hidden characters such as line breaks or extra spaces. |
