Skip to content

The CLI uses API tokens only, not your dashboard email and password. Each token is a Bearer credential scoped to one environment (development, staging, or production).

Get an API token

  1. Sign in to app.truto.one and go to Settings → API Tokens.
  2. Click Create API Token, name it, and pick the environment it should access.
  3. Copy the token immediately. Truto shows the full secret once.
export TRUTO_API_TOKEN="<paste-token-here>"
Danger

Treat API tokens like passwords. Anyone with one can call Truto's APIs as your team in that environment. Never commit a token to git or paste it in a public channel.

A token only works in the environment it was created for. A staging token can't list production accounts. You can list and view tokens with truto api-tokens list / get <id>. Create and delete them in the dashboard.

Log in

truto login

You're prompted for a profile name, the API base URL, and the token (masked input). The token is checked against the API before it's saved.

truto login --token <your-api-token>
truto login --token <token> --profile-name staging -f
Tip

--token skips every prompt and overwrites an existing profile of the same name, the same effect as -f. Without a terminal and without --token, truto login exits 1 and names the command to run.

Logging in makes the saved profile the active one, so later commands without -p use it.

Logout and verify

truto logout
truto logout --profile-name staging -f
 
truto whoami
truto whoami -p staging -o json

whoami resolves credentials the same way every other command does, so it shows you the token the next command would actually send, and which profile, flag, or variable it came from.

Profiles

A profile saves a token, an API URL and a few settings. Keep one per environment or team.

truto profiles list
truto profiles use staging
truto use staging                              # shortcut for profiles use
truto profiles set api-url https://custom.truto.one
truto profiles set default-integrated-account <account-id>
truto profiles get api-url
  • Profiles live in ~/.truto/config.json (Windows: %USERPROFILE%\.truto\config.json), readable only by you (0600).
  • Use a profile for one command with -p <name>.

Bring-your-own keys

truto integrations build and truto unified-mappings build use your own LLM keys. Save them to a profile:

truto profiles set-key anthropic                # asks for the key (default LLM provider)
truto profiles set-key fireworks                # only for --llm-provider fireworks
truto profiles set-key firecrawl sk-...         # for crawling docs sites
  • set-key saves to the profile -p names (it must exist), else the active profile.
  • A build uses the profile's key when no flag or environment variable sets one.
  • No key anywhere? In a terminal, the build asks for one and offers to save it. It never asks in CI or under -o json.

See AI-powered build for how the keys are used.

Allowed profile keys

Key Aliases
apiUrl api_url, api-url
defaultIntegratedAccount default_integrated_account, default-integrated-account
anthropicApiKey anthropic_api_key, anthropic-api-key
fireworksApiKey fireworks_api_key, fireworks-api-key
firecrawlApiKey firecrawl_api_key, firecrawl-api-key
integrationConfigDir integration_config_dir, integration-config-dir
unifiedMappingDir unified_mapping_dir, unified-mapping-dir

Resolution order

Token:

  1. --token flag (highest priority)
  2. With -p <name>: that profile's apiToken, then TRUTO_API_TOKEN. Without -p: TRUTO_API_TOKEN, then the active profile's apiToken
  3. Error if none found

API URL:

  1. --api-url flag
  2. With -p <name>: that profile's apiUrl, then TRUTO_API_URL. Without -p: TRUTO_API_URL, then the active profile's apiUrl
  3. https://api.truto.one (default)

The token and the API URL resolve separately. When they'd point to different hosts, the command is refused rather than sending one environment's token to another.

Info

Changed in 1.0.39: -p now beats TRUTO_API_URL and TRUTO_API_TOKEN. Earlier versions let the environment variables win, and fell through to them when -p named a profile that didn't exist.

Edge cases

  • A config file that can't be read, isn't valid JSON, or isn't a JSON object is an error for every command. The error names the file but never shows what's in it. truto login never saves over it.
  • An empty file, or valid JSON with no profiles key, counts as no profiles. truto login then writes the file.
  • Saves go through a temporary file and rename, so an interrupted save leaves the previous file in place.
  • A profiles entry that isn't an object, or a field of the wrong type (a number where a token or URL goes), is a config error naming the profile and field, never the value.

Next