gaia dropsh

An entity-agnostic shell over the control plane's JSON:API, bound to the same connection config gaia ui uses. Everything the agents write, you can write by hand with it — which is also why it validates before it sends.

Synopsis

gaia dropsh [--config <path>] [--auth-profile <id>] [--format <id>] [--view-mode <name>] <verb> …

Global options

Option	Meaning
--config <path>	connection config to use (overrides $DROPSH_CONFIG and the walk-up)
--auth-profile <id>	the auth profile: session (default) or pm; overrides the active profile and $DROPSH_AUTH_PROFILE
--format <id>	output: json (default) or a renderer id
--view-mode <name>	entity view mode for interactive renderers (default default)

Targets and envelopes

A target is entity_type/bundle/uuid — gaia_ticket/gaia_ticket/57738e90-…. For every GAIA entity the bundle equals the entity type, except labels: gaia_term/gaia_labels/<uuid>.

An envelope is a JSON:API document with data.type set to <entity>--<bundle> and the fields under attributes and relationships, given inline or as @path. Write it to a file; --dry-run validates it against the cached schema and prints what would be sent without sending.

Verbs

Verb	Options	What it does
read <target>	--include <fields...> sideload relationships	read one entity
search <entity_type>	--bundle <bundle> (required for GAIA entities) · --filter <kv...> · --limit <n> (default 50) · --offset <n> · --sort <field> (prefix - for descending) · --include <fields...>	list entities
create <entity_type>	--bundle <bundle> · --data <json|@path> · --dry-run · --no-validate	create one entity
update <target>	--data <json|@path> · --dry-run · --no-validate	PATCH one entity
delete <target>	--dry-run	delete one entity
upload-file	--target entity_type/bundle/uuid/field_name · --file <path> · --dry-run	upload a file into a file or media field
schema [target]	--for create|update (default create) · --refresh bypass the cache	the catalog (no target) or the JSON Schema for <entity>/<bundle>
auth <subcommand>	login --provider <id> · use <id> · logout [--profile] · status	manage the OAuth profiles

Filter operators

--filter key:value is equality; --filter key:op:value selects an operator. Relationship paths work: ticket_id.id:<uuid>.

Operator	Meaning
= (omitted)	equals
<>, !=	not equals
<, <=, >, >=	comparisons
CONTAINS	substring
STARTS_WITH, ENDS_WITH	prefix / suffix
IN, NOT IN	comma-separated list: --filter state:IN:spec,coding
BETWEEN, NOT BETWEEN	comma-separated low,high
IS NULL, IS NOT NULL	value-less; quote the space so the shell passes one argument: --filter 'origin:IS NULL'

Auth profiles

The connection config declares two OAuth client-credentials profiles that differ only by scope:

Profile	Scope	Use it for
session (default)	gaia:session	the agent's own identity: writes on tickets it holds a claim on
pm	gaia:project_manager	project-manager work from a shell: creating tickets and comments, routing tickets by hand

gaia dropsh auth login --provider pm    # prompts for the client secret unless the env carries it
gaia dropsh auth status                 # host, each profile, its validity
gaia dropsh auth use pm                 # make pm the active profile for this host

Tokens are short-lived and stored per host under ~/.config/dropsh/, mode 0600. A command that meets an expired token says so; log in again and repeat it.

Examples

# the fields a ticket create accepts
gaia dropsh --auth-profile pm schema gaia_ticket/gaia_ticket --for create

# a project's uuid, and the labels
gaia dropsh --auth-profile pm search gaia_project --bundle gaia_project
gaia dropsh --auth-profile pm search gaia_term --bundle gaia_labels

# the comments of one ticket, oldest first
gaia dropsh --auth-profile pm search gaia_comment --bundle gaia_comment \
  --filter ticket_id.id:<ticket uuid> --sort created

# a ticket with its runs sideloaded
gaia dropsh --auth-profile pm read gaia_ticket/gaia_ticket/<uuid> --include runs

# move a ticket to review, validated first
gaia dropsh --auth-profile pm update gaia_ticket/gaia_ticket/<uuid> --data @to-review.json --dry-run
gaia dropsh --auth-profile pm update gaia_ticket/gaia_ticket/<uuid> --data @to-review.json

Rich-text fields — a ticket's description, a comment's body — are Markdown with format: gaia_rich. Leave server-owned fields (identifier, number, state on create, base branch, author) out of an envelope. branch_name is the one exception, at creation only: set it to make a carrier ticket whose branch is a long-lived integration branch that its sub-tickets base on; omitted, the server derives feat/<identifier>-<title>, and either way the value is frozen afterwards.

Next

• Create a ticket — the create envelope in context
• Handoffs & comments — writing a comment
• Connection config — the profiles and where they are declared