Output, queries, and exit codes

Every data-returning command prints a readable table or summary by default and a raw JSON response on demand. A set of global flags controls output and works on any command, in any position.

Global flags

These flags are hoisted before parsing, so microtica --json env list and microtica env list --json are equivalent.

Human output vs JSON

With no flags, list commands print an aligned table and single-object commands print formatted JSON. Add --json to get the raw, unformatted API response for every command — the shape you'd consume in a script.

# Readable table
microtica env list

# Raw JSON for scripting
microtica env list --json

Filter with --query

--query runs a JMESPath expression against the raw response and prints the result as JSON. It implies --json, so you never need both.

# Just the ids
microtica pipeline list --query "[].id"

# Filter, then project specific fields
microtica pipeline list --query "[?automatedTrigger].{id: id, repo: repositoryUrl}"

# Pull a single scalar out of a command's result
microtica pipeline trigger <pipelineId> --ref main --query buildId
# → "8f2c1a4b-…"

Because --query always emits JSON, pipe it through jq -r when you need a newline-separated list for a shell loop:

microtica pipeline list --query "[].id" | jq -r '.[]'

Errors

Every error exits non-zero. The format depends on --json.

Default (human-readable, on stderr):

error: Branch refs/heads/main doesn't exist in repository https://… (HTTP 400)

With --json, the error is a structured object on stderr, leaving stdout clean:

{
  "error": {
    "kind": "api",
    "status": 400,
    "code": 400,
    "message": "Branch refs/heads/main doesn't exist in repository …",
    "details": { "code": 400, "message": "…" }
  }
}

kind classifies the failure:

Exit codes

Most commands follow a simple convention:

• 0 — success
• 1 — any error (API, validation, or local precondition)

The logs commands use a richer set so an agent can tell a tooling failure apart from an observed deployment failure:

• 0 — clean exit, success (or no observable status)
• 1 — CLI or API error (validation, auth, network)
• 2 — the stream didn't end cleanly: interrupted, disconnected, or timed out
• 3 — clean exit, but the observed result was a failure or cancellation

A non-zero exit code with output on stderr is the reliable failure signal. Don't parse stdout to detect failure — on error it may be empty or hold only partial output.

Next steps

• Browse the command reference
• Stream build and deployment logs