stackgen api

Text size

stackgen api

Use stackgen api to call StackGen mothership HTTP APIs with the same login token and project (orgId) the CLI already uses. Prefer this over hand-rolled curl when you know the REST path but there is no dedicated stackgen subcommand.

Paths are mothership-relative by default (joined to STACKGEN_URL). Use --service to resolve a path against a path.json service base (for example Guild / Aiden). Absolute URLs are rejected. JSON responses are pretty-printed by default; filter with --jq or --jsonpath.

Prerequisites

• Authenticate with stackgen login (or set STACKGEN_URL, STACKGEN_TOKEN, and STACKGEN_PROJECT / --project).
• Know the mothership path, or use --service with a service-relative path.

Usage

stackgen api <path> [flags]

Flags

Flag	Description
-X, --method string	HTTP method: GET, POST, PUT, PATCH, DELETE (default GET)
--service string	Resolve <path> against a path.json base (see Services)
--input string	JSON body file path, or - for stdin
-f, --field stringArray	Add a string field to the JSON body as key=value (repeatable; merges into --input when both are set)
--jq string	Filter or transform the JSON response with a jq expression
--jsonpath string	Filter the JSON response with a JSONPath expression ($.items[*].name or kubectl-style {.items[*].name})
--compact	Print JSON on a single line
--include-secrets	Do not redact common secret JSON keys (token, api_key, and similar)
-h, --help	Help for api

Global flags

See Global flags for --project, --workspace, --output, --interactive, --log, --stackgen-home, and other options. When a project is set, orgId is added to the request query string automatically.

Path shapes

Form	Example	Resolves to
Mothership-relative	/guild/api/v1/agents	{STACKGEN_URL}/guild/api/v1/agents
With query string	/guild/api/v1/agents?page_size=1	Same base, query preserved
Service shorthand	--service guild /api/v1/agents	{STACKGEN_URL} + Guild path from path.json + /api/v1/agents
Absolute URL	https://…	Rejected

A leading / is added if you omit it. The path must include a resource (bare / is invalid).

Services

--service joins your path to the matching path.json base. Aliases are accepted:

Service	Aliases
appcd
guild	aiden
vault
iac-gen	iacgen
deployment-manager	deploymentmanager
exporter	stack-exporter
auth

stackgen api --service aiden /api/v1/agents
stackgen api --service appcd /v1/projects

Examples

List Aiden agents

# Full mothership path
stackgen api /guild/api/v1/agents

# Same call via --service
stackgen api --service guild /api/v1/agents

# Limit with a query string on the path
stackgen api /guild/api/v1/agents?page_size=5

Filter JSON with --jq

# First agent name (string results print without JSON quotes)
stackgen api --service guild /api/v1/agents --jq '.[0].name'

# How many agents, single line
stackgen api /guild/api/v1/agents --jq 'length' --compact

Filter JSON with --jsonpath

# Goessner-style
stackgen api --service guild /api/v1/agents --jsonpath '$[0].name'

# kubectl-style braces (root array)
stackgen api --service guild /api/v1/agents --jsonpath '{.[0].name}'

# Object list field
stackgen api --service guild /api/v1/agents --jsonpath '{.items[*].name}'

Compact JSON without a filter

stackgen api --service guild /api/v1/agents --compact

POST, PUT, PATCH, or DELETE with a body

# Body from a file
stackgen api -X POST --service guild /api/v1/agents --input body.json

# Body from stdin
echo '{"name":"example"}' | stackgen api -X POST --service guild /api/v1/agents --input -

# Body from --field only (all values are strings)
stackgen api -X PUT --service guild /api/v1/some-resource \
  -f name=example \
  -f enabled=true

# Merge --field into a JSON object from --input
stackgen api -X PATCH --service guild /api/v1/some-resource \
  --input base.json \
  -f status=active

# No body
stackgen api -X DELETE --service guild /api/v1/agents/agent-id

Project scoping

stackgen api --project my-project --service guild /api/v1/agents --jq 'length'
# or
STACKGEN_PROJECT=<org-uuid> stackgen api --service guild /api/v1/agents

Secrets in responses

By default, common secret JSON keys (token, access_token, api_key, password, secret, and similar) are replaced with [REDACTED].

# Keep raw secret fields (use only when you need them locally)
stackgen api --service vault /v1/some-secret --include-secrets

Behavior notes

• Non-2xx responses exit non-zero and print HTTP <status>: <body>.
• Request and response bodies are capped at 1 MiB.
• Empty 2xx bodies print METHOD <path> → empty body.
• Non-JSON bodies print as-is. --jq / --jsonpath require JSON and fail otherwise.
• Use only one of --jq or --jsonpath on a single invocation.
• --field values are always strings. For typed JSON (numbers, booleans, nested objects), pass a full JSON body with --input.
• --input must be a JSON object when you also pass -f (fields are merged into that object).