CLI commands

Global options

Global options can be placed before a command group.

This workflow guide covers every command group in CLI 1.1.0. For exact syntax, arguments, options, defaults, choices, API operations, scopes, output behavior, confirmations, examples, and exit codes, use the generated CLI command reference. It is derived from the same Commander tree as the released package and checked against the API capability manifest.

The installed CLI remains the authoritative source for the patch release actually on the machine:

teamgrid --help
teamgrid <group> --help
teamgrid <group> <command> --help

Run teamgrid --version before comparing terminal output with this reference. Commands map to API v1 operations and never bypass the credential’s workspace, scopes, resource grants, or regional routing. A command that is absent from --help is not supported by the installed version.

Authentication and workspace

teamgrid auth login [--preset read-only|daily-work] [--scope SCOPE]
  [--no-browser|--manual|--token-stdin] [--replace]
teamgrid auth logout [--revoke]
teamgrid auth profiles
teamgrid auth status [--check]
teamgrid doctor
teamgrid api-version
teamgrid workspace
teamgrid system capabilities
teamgrid workspace entitlements

Platform discovery and settings

teamgrid system capabilities
teamgrid workspace entitlements
teamgrid workspace-settings get
teamgrid workspace-settings update --data <json|@file|->
  --if-match REVISION --idempotency-key KEY
teamgrid events catalog

Read workspace settings first and pass the returned wst1 revision or strong ETag to update. A 412 means another administrator changed the safe settings snapshot; re-read it before deciding whether to retry. The settings projection contains only six documented fields and never provider, billing, storage, role, or integration configuration. Capability, entitlement, and event responses are current negotiation results, not permanent authorization grants.

Credentials and service accounts

teamgrid credentials personal list|create|rotate|revoke
teamgrid service-accounts list|create|get|update|revoke
teamgrid service-accounts credentials create|rotate|revoke
teamgrid service-accounts grants get|replace --if-match REVISION

Credential secrets are returned once. Move them directly into a secret manager. Resource-grant replacement is a complete compare-and-set operation; read the current grant revision before replacing it.

Browser login is the default authentication path. --no-browser prints the private approval URL but still requires the loopback callback to reach the CLI host. --manual prompts for an existing personal or service credential; --token-stdin reads it without placing it in process arguments. auth status --check retrieves the exact server-side context of the active credential without requiring an extra scope. auth logout is local only. auth logout --revoke first revokes exactly the selected saved credential, then removes its keychain entry and profile; if revocation fails, local access is preserved so the operation can be diagnosed and retried. Unset TEAMGRID_API_TOKEN before using --revoke because an environment override makes the target ambiguous. The complete flow and recovery guidance are documented under browser login.

teamgrid doctor performs only read operations and checks local configuration, credential and routing metadata, the resolved regional endpoint, network reachability, CLI/API compatibility, and authenticated capability discovery. Use teamgrid --output json doctor for a stable, redacted support or automation report.

Projects and lifecycle operations

teamgrid projects list|get|create|update
teamgrid projects sharing get PROJECT_ID
teamgrid projects sharing replace PROJECT_ID --data <json|@file|-> --if-match REVISION
teamgrid projects complete|reopen|archive|restore PROJECT_ID [--wait]
teamgrid project-lifecycle-operations get OPERATION_ID

List commands accept --limit, --cursor, --all, and --max-pages. Resource-specific filters are visible through teamgrid <command> --help.

Examples:

teamgrid projects list --completed false
teamgrid projects create --data @project.json --idempotency-key project-import-42
teamgrid projects get PROJECT_ID --output json
teamgrid projects update PROJECT_ID --data '{"color":"#3772ff"}' --if-match REVISION
teamgrid projects complete PROJECT_ID \
  --if-match REVISION --idempotency-key close-42 --wait

Recurring tasks

teamgrid task-recurrences list|get|create|preview|update
teamgrid task-recurrences pause|resume|end|archive|restore SERIES_ID --if-match REVISION
teamgrid task-recurrences preview-stored SERIES_ID
teamgrid task-recurrences owner SERIES_ID --data <json|@file|-> --if-match REVISION
teamgrid task-recurrences template-from-task SERIES_ID --data <json|@file|-> --if-match REVISION
teamgrid task-recurrences versions list|get|restore
teamgrid task-recurrences occurrences list|get|override|clear-override|retry
teamgrid task-recurrences recheck SERIES_ID [--wait]
teamgrid task-recurrences events submit SERIES_ID --data <json|@file|->
teamgrid task-recurrence-operations get|wait|cancel OPERATION_ID

Series and existing occurrence mutations use separate strong revisions. A future occurrence from preview-stored uses occurrences override --create-if-missing plus the opaque placeholderToken in its JSON; this flag is mutually exclusive with --if-match. Archive, end and operation cancel also require --yes in non-interactive use. An unsaved high-cost preview returns an operation; pass its ID to task-recurrence-operations wait. See Recurring tasks for immutable-version, occurrence identity, trigger idempotency and recovery semantics.

Project lists support --archived, --completed, --contact-id, --created-by-id, --individual-id, --list-id, --manager-id, and --subscriber-id. Multiple filters are combined and never broaden the credential’s workspace boundary.

Project lifecycle commands create durable asynchronous operations. Without --wait, the command returns the operation immediately. With --wait, it polls until a terminal state, bounded by --max-wait and --poll-interval. Lifecycle access uses the separate projects:lifecycle scope. Project updates and lifecycle commands require --if-match from the latest project read. Lifecycle starts should also use a stable idempotency key.

Project sharing replacement sends the complete desired entry set. It validates local members and accepted workspace connections and never permits an unvalidated cross-region user identifier.

Commerce and project statements

teamgrid products list|get|create|update|archive
teamgrid product-groups list|get|create|update|archive
teamgrid project-statements list|get|create|update|archive|restore

Product list filters include --archived, --disabled, and --product-group-id. Product-group list filters include --archived and --parent-id. Products and product groups do not expose a restore command in the current contract.

Project-statement list filters are:

--archived BOOLEAN
--created-at-from DATE
--created-at-to DATE
--created-by ID
--date-from DATE
--date-to DATE
--product-id ID
--project-id ID
--type budget|bundle|manual|product

Examples:

teamgrid products list --disabled false --product-group-id GROUP_ID --all --output json
teamgrid products create --data @product.json --idempotency-key product-import-42
teamgrid product-groups update GROUP_ID --data '{"parentId":"PARENT_GROUP_ID"}'
teamgrid project-statements list --project-id PROJECT_ID --date-from 2026-07-01T00:00:00Z
teamgrid project-statements restore STATEMENT_ID

Product purchasePrice and project-statement budget or acquisition-cost data require the additional finance scopes documented under credentials and scopes. CLI JSON output omits finance-gated values when the credential lacks the matching finance read scope.

Lists, services, and tags

Each metadata group supports list, get, create, update, archive, and restore. The bare group remains an alias for its list command.

teamgrid lists [list] [--type tasks|projects|personal] [--parent-id ID] [--archived BOOLEAN]
teamgrid lists get|archive|restore LIST_ID
teamgrid lists create --data <json|@file|-> [--idempotency-key KEY]
teamgrid lists update LIST_ID --data <json|@file|->

teamgrid services [list] [--archived BOOLEAN]
teamgrid services get|archive|restore SERVICE_ID
teamgrid services create --data <json|@file|-> [--idempotency-key KEY]
teamgrid services update SERVICE_ID --data <json|@file|->

teamgrid tags [list] [--archived BOOLEAN]
teamgrid tags get|archive|restore TAG_ID
teamgrid tags create --data <json|@file|-> [--idempotency-key KEY]
teamgrid tags update TAG_ID --data <json|@file|->

Examples:

teamgrid lists create --data '{"name":"Delivery","type":"tasks","parentId":"PROJECT_ID"}' --idempotency-key list-42
teamgrid services update SERVICE_ID --data '{"billable":true,"billingRate":145}'
teamgrid tags create --data '{"name":"Priority","color":"#3772ff"}' --idempotency-key tag-42
teamgrid tags archive TAG_ID --yes
teamgrid tags restore TAG_ID

List creation supports tasks and projects; personal is a read filter for existing personal lists and is not an accepted public create type. Service responses can contain billing rates, so service credentials and machine-readable output should be handled as commercially sensitive data.

Tasks

teamgrid tasks list --project-id PROJECT_ID --completed false
teamgrid tasks get TASK_ID --output json
teamgrid tasks create --data @task.json --idempotency-key task-import-42
teamgrid tasks update TASK_ID --data '{"name":"Updated task name"}' --if-match REVISION
teamgrid tasks duplicate TASK_ID --data '{"copyChecklist":true}' \
  --if-match REVISION --idempotency-key task-copy-42
teamgrid tasks move TASK_ID --data @placement.json --if-match REVISION
teamgrid tasks subtasks replace TASK_ID --data @checklist.json --if-match REVISION
teamgrid tasks archive TASK_ID --if-match REVISION
teamgrid tasks restore TASK_ID --if-match REVISION
teamgrid tasks complete TASK_ID --if-match REVISION
teamgrid tasks reopen TASK_ID --if-match REVISION
teamgrid tasks timer start TASK_ID --user-id USER_ID
teamgrid tasks timer stop TASK_ID --user-id USER_ID

Task lists accept --archived, --completed, --assignee-id, --contact-id, --group-id, --list-id, --personal-list-id, --project-id, --service-id, --subscriber-id, and --tag-id. Multiple filters are combined. Use --all for bounded automatic pagination.

Use the explicit complete and reopen commands for task state transitions. Timer commands accept an optional --at <date> ISO timestamp. When omitted, the API receive time is used. Starting a timer can stop the same user’s previous timer and update task tracking state, so the credential must grant both tasks:write and time-entries:write.

Task mutations require --if-match from the latest task read. Do not synthesize a revision from updatedAt or another task field.

Task descriptions have an explicit format. Existing and unmarked content remains literal plain-text. To create intentionally formatted content, put both fields in the request file:

{
  "name": "Prepare release",
  "description": "# Acceptance criteria\n\n- Verify staging\n- Publish notes",
  "descriptionFormat": "markdown-v1"
}

Then run teamgrid tasks create --data @task.json --idempotency-key prepare-release-1. An update uses the same paired fields plus --if-match from teamgrid tasks get TASK_ID --output json. Omitting descriptionFormat deliberately creates plain text; sending the format without a non-null description is rejected.

Time entries

time-entries also has the alias times.

teamgrid time-entries list --from 2026-07-01 --to 2026-07-31 --all
teamgrid times list --service-id SERVICE_ID --billable true --billed false
teamgrid times get TIME_ENTRY_ID
teamgrid times create --data @time-entry.json --idempotency-key time-import-42
teamgrid times update TIME_ENTRY_ID --data @time-entry-patch.json
teamgrid time-entries billing get TIME_ENTRY_ID
teamgrid time-entries billing update TIME_ENTRY_ID --data @billing.json --if-match REVISION
teamgrid times archive TIME_ENTRY_ID
teamgrid times restore TIME_ENTRY_ID

Contacts, call notes, and contact groups

teamgrid contacts list|get|create|update
teamgrid call-notes list|get|create|archive|restore
teamgrid contact-groups list|get|create|update|archive|restore
teamgrid users

Contact lists accept type, category, company, creator, customer, group, parent-contact, and archive filters. Call-note and contact-group lists accept --archived. Call-note creation accepts plain-text content; the API does not expose TeamGrid’s internal rich-text representation. Contact-group parent changes are validated against cycles and hierarchy limits.

teamgrid contacts list --type company --all --output json
teamgrid contacts create --data @contact.json --idempotency-key contact-import-42
teamgrid call-notes create --data @call-note.json --idempotency-key call-note-42
teamgrid contact-groups update GROUP_ID --data '{"parentId":"PARENT_GROUP_ID"}'

Custom-field definitions

teamgrid custom-field-definitions list|get|create|update|archive|restore

List filters include --archived, --default-enabled, --field-type, and --target-type. Canonical field types are contact, date, dropdown, number, project, switcher, tag, text, textarea, and user. Target types are contact, project, projectJournalEntry, and task.

Custom-field values

teamgrid custom-field-values get TARGET_TYPE RESOURCE_ID FIELD_ID
teamgrid custom-field-values get-many TARGET_TYPE RESOURCE_ID
  --field-id FIELD_ID [FIELD_ID...]
teamgrid custom-field-values set TARGET_TYPE RESOURCE_ID FIELD_ID
  --data <json|@file|-> --if-match REVISION
teamgrid custom-field-values clear TARGET_TYPE RESOURCE_ID FIELD_ID
  --if-match REVISION --yes

get-many accepts 1–100 unique field IDs and preserves their order. Read first, then pass the latest data.attributes.revision to --if-match. A 412 means another writer changed the value; re-read and decide explicitly instead of blindly retrying. Clear is a destructive compare-and-set operation and therefore requires confirmation.

Project templates

teamgrid project-templates list|get|create
teamgrid project-templates update|archive|restore PROJECT_TEMPLATE_ID
teamgrid project-templates instantiate TEMPLATE_ID --data <json|@file|->
  --if-match REVISION [--idempotency-key KEY] [--wait]
teamgrid project-template-instantiations get OPERATION_ID

Template list filters include --archived, --created-at-from, --created-at-to, and --origin-project-id. Create and instantiate should use stable idempotency keys. --wait polls the credential-owned instantiation until it succeeds or fails, bounded by --max-wait and --poll-interval. Project-template mutations require --if-match from the latest template read. Instantiation binds its payload and source revision to the idempotency key.

Planned work

teamgrid planned-work list --start DATE --end DATE
  [--project-id ID] [--task-id ID] [--user-id ID]
teamgrid planned-work get TASK_ID
teamgrid planned-work replace TASK_ID --data <json|@file|->
  --if-match REVISION [--idempotency-key KEY] --yes [--wait]
teamgrid planned-work-operations get OPERATION_ID

Replacement overwrites the complete task schedule. Read the latest task schedule, pass its revision to --if-match, use a stable idempotency key, and use --yes for non-interactive execution. A successful 202 only accepts the operation; use --wait or poll the operation group before relying on the replacement.

Calendar, absence, and availability

teamgrid appointments list|get|create|update|archive|restore
teamgrid absences list|get|create|update|archive|restore
teamgrid availability list

List operations require bounded --start and --end values; availability also requires an IANA time zone. Acting for another member requires the delegated or administrative overlay scope and the underlying TeamGrid sharing and product permission. Updates use --if-match; creates accept an idempotency key.

Comments, activity, documents, and files

teamgrid comments list|get|create|archive|restore
teamgrid activity list
teamgrid documents list|get|create|update|archive|restore
teamgrid files list|get|rename|archive|restore|download-intent
teamgrid file-upload-intents create|finalize|cancel

Comments and activity require a contact, project, or task target plus its matching domain scope. Document updates are compare-and-set operations. File upload and download intents are short-lived private capabilities; do not log them or pass them in URLs.

Workspace administration

teamgrid members list|get|update-role|remove
teamgrid invitations list|get|create|resend|cancel
teamgrid roles list|get|create|update|remove
teamgrid groups list|get|create|update|remove

Use dedicated administration credentials. Member and invitation PII requires the separate members:pii:read overlay. Mutations that change existing authorization state require the latest strong revision through --if-match; destructive commands require confirmation.

Change feed

teamgrid changes checkpoint [--resource-type TYPE] [--operation OPERATION]
teamgrid changes list --cursor CURSOR [--resource-type TYPE] [--operation OPERATION] [--all]

Persist each returned cursor only after applying its page durably. Checkpoints are bound to the credential, workspace, cell, epoch, and exact filter set.

Search and exports

teamgrid search query --data <json|@file|->
teamgrid exports create --data <json|@file|-> [--idempotency-key KEY]
teamgrid exports get EXPORT_ID
teamgrid exports download-intent EXPORT_ID
teamgrid exports download EXPORT_ID (--file PATH | --stdout)
  [--intent-token-stdin] [--max-bytes NUMBER]

By default, exports download creates the short-lived intent internally. To separate the two steps, pipe the token through standard input with --intent-token-stdin; it is never accepted on the command line or in a URL. --file creates a mode-0600 file exclusively and never overwrites an existing path. --stdout refuses to write binary data to a terminal. Both paths enforce a maximum of 50 MiB. Audit exports use resourceType: "auditEvents" and require an immutable createdAtTo boundary.

Automations and integrations

teamgrid automation-actions list
teamgrid automation-definitions list|get|create|update|archive|restore
teamgrid automation-definition-versions list DEFINITION_ID
teamgrid automation-runs list|get|abort
teamgrid integration-installations list

Automation definition updates use their latest aut1 revision; aborting a run uses its latest aur1 revision. The integration command returns redacted installation status, not provider tokens or configuration secrets.

Audit events

teamgrid audit-events [--actor-id ID] [--actor-type user|serviceCredential|system]
                      [--created-at-from ISO] [--created-at-to ISO]
                      [--credential-id ID] [--event-type TYPE]
                      [--outcome success|denied|failure] [--request-id ID]
                      [--source teamgrid-app|api-v1|system]
                      [--target-id ID] [--target-type TYPE]

Filters are combined and bound into the opaque pagination cursor, so a cursor cannot be reused with another credential, cell, region, or filter set. JSON output includes meta.retentionDays, the configured retention of the serving cell (30–3650 days; 365 by default). Audit output can contain security-sensitive operational metadata. Limit access and retention in downstream systems.

Webhooks and delivery history

teamgrid webhooks list
teamgrid webhooks get WEBHOOK_ID
teamgrid webhooks create --data @webhook.json --idempotency-key webhook-42
  (--secret-file PATH | --secret-stdout)
teamgrid webhooks remove WEBHOOK_ID
teamgrid webhooks rotate-secret WEBHOOK_ID --if-match REVISION
  [--idempotency-key KEY] (--secret-file PATH | --secret-stdout) [--yes]
teamgrid webhook-deliveries list --webhook-id WEBHOOK_ID --state failed --event task_updated
teamgrid webhook-deliveries get DELIVERY_ID

Webhook create and rotate-secret require exactly one explicit secret destination. Rotation also asks for confirmation. --secret-file is recommended: it creates a new mode-0600 file atomically and never overwrites an existing path; normal output contains only a secret-free receipt. --secret-stdout emits only the raw secret plus a newline and no metadata, for an explicitly controlled pipe into a secret manager; it refuses to write to an interactive terminal. The secret is never accepted in an argument or URL and is never sent through table, JSON, stderr, or debug output. Reuse the same idempotency key and precondition to recover the same rotation after a lost response.

Delivery history requires webhooks:read and returns only records owned by the authenticated credential. List filters include --webhook-id, --event, and --state delivering|failed|retrying|skipped|succeeded. URLs, payloads, headers, bodies, and secrets are never returned.

--data accepts inline JSON, @path/to/file.json, or - for standard input. Archive, remove, and secret-rotation commands ask for confirmation; use --yes only in an intentionally non-interactive workflow.