Use the CLI with AI agents
Drive Microtica from Claude Code, Cursor, or any AI harness using the CLI's built-in agent reference, JSON output, and structured errors.
The Microtica CLI is built to be driven by AI coding agents as much as by people. Output is JSON on demand, errors are structured, exit codes are meaningful, and the CLI ships its own reference that an agent can read at runtime.
The built-in agent reference
microtica agents prints a reference written for LLM agents — focused on the JSON shape each command returns, plus --query recipes and common pitfalls. An agent can call it to learn the surface without you pasting docs into the conversation.
# Compact index: setup, global flags, the topic list, and exit codes
microtica agents
# One topic in full
microtica agents env
# The complete reference
microtica agents --full
# Just the topic names, one per line
microtica agents --listTopics map to the command groups:
| Topic | Covers |
|---|---|
project | Identity and projects — whoami, project list/get. |
env | Environments — deploy, clone, replicate, resources, last-deploy. |
app | Kubernetes apps — deploy, scaling, status, logs, last-deploy. |
git | Git accounts, repositories, branches. |
pipeline | Pipelines and builds — history, list, create, trigger. |
logs | Build, deployment, and app log streaming. |
query | JMESPath --query recipes and shell-piping tips. |
pitfalls | Common mistakes and Microtica-specific gotchas. |
Starting with the index (no arguments) keeps the agent's context small: it's about 3 KB, and the agent can pull only the topic it needs.
Why it works well for agents
- JSON-first. Add
--jsonor--queryto any data command for a machine-readable response.--queryreshapes it server-agnostically with JMESPath. - Structured errors. With
--json, errors are objects on stderr (kind,status,message) while stdout stays clean — easy to parse and act on. - Meaningful exit codes. The
logscommands distinguish a tooling failure from an observed deployment failure, so an agent can branch on the exit code instead of scraping text. - Same contract as the SDK. The CLI wraps the Microtica SDK, so an agent gets identical behavior whether it shells out or calls the typed client.
Point your harness at it
In Claude Code, Cursor, Cline, or any agent with shell access, tell the agent it can run microtica agents to discover command output shapes, and to prefer --query with explicit field selection over consuming whole payloads. The reference also ships as an AGENTS.md file inside the installed package, so agents that read repository context files can pick it up directly.