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 With -p, that profile's URL, then TRUTO_API_URL; without it, TRUTO_API_URL, then the active profile's URL; then https://api.truto.one
--token <token> Override API token With -p, that profile's token, then TRUTO_API_TOKEN; without it, TRUTO_API_TOKEN, then the active profile's 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 budget is 3 retries, with backoff of 0.5s, 1s and 2s (with jitter), capped at 10s per wait.

  • A Retry-After header from the server replaces the delay, with the same 10s cap.

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.

Tip

Want CI to fail fast? Set TRUTO_MAX_RETRIES=0 to turn retrying off.

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
Admin commands, including get table
export json (unless -o is set)
custom json

Pagination

List commands return 25 results by default:

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

truto integrations list is the exception: it returns the whole integration catalog available to your team in one response, so --limit and --next-cursor have no effect on it.

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, update 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 Return only the summary fields, the same columns list shows
--like <field=pattern> list Case-sensitive LIKE filter on a column, % / _ wildcards (repeatable)
--ilike <field=pattern> list Case-insensitive ILIKE filter on a column (repeatable, 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 and update (admin resources), unified, proxy, custom, and batch:

  • Admin create: input that starts with [ is a JSON array (bulk create). Anything else is NDJSON, one object per line.
  • Admin update: parsed the same way. Each object is sent as its own update to the given ID, in order.
    • A record refused after earlier ones were sent stops the run with exit 2, and says how many were sent.
    • integrations update takes one record. More are refused before anything is sent.
  • Every record must be one JSON object. So must -b. Anything else (invalid JSON, a number, a string, null, a list) is refused with exit 1 before anything is sent.
    • The refusal never quotes your text, which could be a token. It names the record by position, for example --stdin record 2 is not valid JSON.
  • Data plane and batch: stdin is always one JSON body.
  • --stdin or -b, not both. For data-plane commands -b wins; for admin create and update, --stdin wins.

See Power features for full stdin examples.