CLI automation

Prefer structured output

Use --output json for one response and --output jsonl for a stream of resources. Table output is intended for humans and may evolve for readability.

teamgrid tasks list --project-id "$PROJECT_ID" --all --output jsonl \
  | jq -r '.id'

--all follows opaque cursors and stops at 10,000 pages by default. Lower the guard with --max-pages when a job should have a tighter upper bound.

For a durable mirror, create a checkpoint before the initial resource traversal, then catch up from that exact cursor:

checkpoint=$(teamgrid changes checkpoint --resource-type task --output json \
  | jq -er '.meta.page.nextCursor')

teamgrid tasks list --all --output jsonl > tasks.snapshot.jsonl
teamgrid changes list --cursor "$checkpoint" --resource-type task --all --output jsonl

Persist each new cursor only after applying its page durably. Do not decode a cursor, move it between cells, or change its filters. See the change-feed recovery contract before operating a mirror.

Make retried writes idempotent

Supply a stable, operation-specific idempotency key for creates:

teamgrid tasks create \
  --data @task.json \
  --idempotency-key "sync-${RUN_ID}-${SOURCE_TASK_ID}" \
  --output json

GET requests, POST requests carrying an idempotency key, and compare-and-set planned-work PUTs with an idempotency key can be retried after bounded transient failures. Other PUT, PATCH, and DELETE requests are not retried automatically.

Custom-field-value and planned-work writes also require the revision returned by the latest GET. For example, read a custom-field value before changing it:

revision=$(teamgrid custom-field-values get project "$PROJECT_ID" "$FIELD_ID" \
  --output json | jq -er '.attributes.revision')

if ! teamgrid custom-field-values set project "$PROJECT_ID" "$FIELD_ID" \
  --data @value.json --if-match "$revision" --output json; then
  # Re-read and reconcile here. Do not substitute the old revision.
  exit 1
fi

Treat 412 and exit code 6 as a concurrent-edit decision, not a generic retry. Missing --if-match is rejected locally; an API 428 maps to usage exit code 2. Planned-work replacement overwrites the complete schedule and requires --yes in non-interactive execution. Project, task, and project-template mutations also require --if-match from their latest read.

Exit codes

Do not parse human-readable error messages to decide control flow. Use the exit code and, when needed, call API v1 through the SDK for typed error details.

CI checklist

• Create a dedicated service account; never use teamgrid auth login or a personal credential in CI.
• Store TEAMGRID_API_TOKEN in the CI secret store and mask it in logs.
• Grant only the scopes the job needs.
• Use JSON or JSONL output.
• Use stable idempotency keys for creates.
• Set explicit timeout, retries, and pagination bounds for long-running jobs.
• Add --yes only to reviewed archive, remove, clear, or full-replacement steps.

For shell-specific input, private certificate authorities, debug output, and recovery by exit code, continue with CLI maintenance and troubleshooting. For the exact options and API scope of every command, use the generated CLI command reference.