api

spacectl api

spacectl api lets you run ad-hoc GraphQL operations against the Spacelift API using your existing authentication.

The provided document is sent unchanged to the API, so queries and mutations are both supported.

Usage

Basic queries:

spacectl api '{ stacks { id name state } }'
spacectl api '{ workerPools { id name workers { id } } }'

Full query syntax:

spacectl api 'query { stack(id: "my-stack") { id name branch repository } }'

With variables:

spacectl api --variables '{"id":"my-stack"}' 'query($id: ID!) { stack(id: $id) { id name } }'

Mutations:

spacectl api 'mutation { stackDelete(id: "my-stack") { id } }'
spacectl api 'mutation DeleteStack($id: ID!) { stackDelete(id: $id) { id } }' --variables '{"id":"my-stack"}'

From a file or stdin:

spacectl api < query.graphql
spacectl api --variables '{"id":"my-stack"}' < query.graphql
cat query.graphql | spacectl api
spacectl api < mutation.graphql

Output

• When stdout is a TTY, output is pretty-printed JSON.
• When piped, output is raw JSON (suitable for jq).
• Use --raw to force raw output.

spacectl api 'stacks { id name repository }' | jq '.data.stacks[] | select(.repository == "tf-infra")'

Schema Introspection

Use --schema to dump the full GraphQL schema via introspection:

# Full schema dump
spacectl api --schema > schema.json

# List all query names
spacectl api --schema | jq '[.data.__schema.types[] | select(.name == "Query") | .fields[].name] | sort'

# List all mutation names
spacectl api --schema | jq '[.data.__schema.types[] | select(.name == "Mutation") | .fields[].name] | sort'

# Inspect a specific type
spacectl api --schema | jq '.data.__schema.types[] | select(.name == "Stack")'

# List enum values
spacectl api --schema | jq '.data.__schema.types[] | select(.name == "RunState") | .enumValues[].name'

You can also run targeted introspection queries directly:

# List all queries
spacectl api '{ __type(name: "Query") { fields { name } } }' | jq '.data.__type.fields[].name'

# Inspect a specific query's arguments
spacectl api '{ __type(name: "Query") { fields { name args { name type { name kind ofType { name } } } } } }' \
  | jq '.data.__type.fields[] | select(.name == "stack")'

# List all types (excluding internals)
spacectl api '{ __schema { types { name kind } } }' | jq '[.data.__schema.types[] | select(.name | startswith("__") | not) | .name] | sort'