Skip to content

Global options

Every command accepts these flags. They can appear anywhere on the command line (before or after the subcommand).

Flag Description Default
-p, --profile <name> Use a specific profile Active profile
--api-url <url> Override API URL Profile URL or https://api.truto.one
--token <token> Override API token Profile token
-o, --output <format> json, table, yaml, csv, ndjson table
-v, --verbose Print request/response details to stderr Off
--no-color Disable colored output Off
--no-help-on-error Suppress automatic --help on errors (for piping) Off

Format shortcuts: --json, --yaml, --csv, and --ndjson are shorthand for -o json, -o yaml, and so on.

Flag aliases: Snake_case and camelCase variants work on most flags (for example --tenant-id, --tenant_id, and --tenantId are equivalent). Dotted API field names become kebab-case flags (integration.name → --integration-name).

Tip

When -o is json, yaml, csv, or ndjson, decorative status messages are suppressed on stdout so only structured data is emitted. Errors always go to stderr.

Transient errors and retries

Every API call the CLI makes retries on its own when the failure is one that a moment later usually fixes:

  • 429 Too Many Requests on any method. The API rejected the request before running it (this is what an overloaded database returns), so replaying it is always safe.
  • 502 / 503 / 504 and network errors (connection reset, DNS, TLS) on GET, HEAD, OPTIONS, PUT and DELETE only. A POST or PATCH that reached the server before the connection dropped may already have been applied, so those surface the error instead.

A 500 is never retried. The default budget is 3 retries with exponential backoff (0.5s, 1s, 2s, with jitter), capped at 10s per wait; a Retry-After header from the server wins over the computed delay.

On a terminal, or with --verbose, each retry prints a dim line to stderr:

⟳ 429 Too Many Requests on GET /integration/865df83b-… — retrying in 1.0s (1/3)

When stderr is a pipe the retries are silent, so a scripted run still sees exactly one error envelope.

Set TRUTO_MAX_RETRIES to change the budget. TRUTO_MAX_RETRIES=0 turns retrying off, which is what a CI job that wants fail-fast behaviour should set.

Output formats

Format Best for Notes
table Interactive inspection Default. Truncates long values; up to 8 columns.
json Piping to jq, saving files Pretty-printed, 2-space indent.
ndjson Streaming, log processing One JSON object per line. Ideal for export.
csv Spreadsheets Columns from first record.
yaml Human-readable nested data

Some commands override the default:

Command Default output
Most admin commands table
export json (unless -o is set)
get subcommands json
custom json

Pagination

List commands return 25 results by default:

truto integrations list --limit 10
# Output shows: Next page: --next-cursor abc123...
truto integrations list --limit 10 --next-cursor abc123

For exhaustive pagination across data-plane resources, use truto export instead.

Shared resource flags

Most admin resource commands support:

Flag Operation Description
--next-cursor <cursor> list Next page
--limit <n> list Results per page (default 25)
--stdin create Body from stdin (JSON array or NDJSON)
-i, --interactive update Pre-fill fields from current record
-f, --force delete Skip confirmation
--select <fields> list, get Comma-separated fields to return (supports dotted paths)
--brief get Omit nested objects from output
--like <pattern> list Case-sensitive LIKE filter (where supported)
--ilike <pattern> list Case-insensitive ILIKE filter (where supported)

On unified, proxy, custom, and unified test-mapping, pass query params with -q key=value (repeatable), --query-json '{"limit":10}', or --query-file params.json.

Filtering

List commands accept --<field> filters. Check per-command help:

truto integrations list --help
truto accounts list --tenant-id <tid>
truto sync-jobs list --integration_name hubspot

Scripting examples

# IDs as JSON
truto integrations list -o json | jq '.[].id'
 
# Count exported records
truto export crm/contacts -a <account-id> -o ndjson | wc -l
 
# Debug HTTP
truto integrations list -v
# stderr: → GET https://api.truto.one/integration?limit=25
#         ← 200 OK

Stdin and --body

On create (admin resources), unified, proxy, custom, and batch:

  • Admin create: Input starting with [ → JSON array (bulk create); otherwise NDJSON (one object per line).
  • Data plane / batch: Stdin is always a single JSON body.
  • --stdin and -b are mutually exclusive. For data-plane commands, -b wins; for admin create, --stdin wins.

See Power features for full stdin examples.