Authentication
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
- Sign in to app.truto.one and go to Settings → API Tokens.
- Click Create API Token, name it, and pick the environment it should access.
- Copy the token immediately. Truto shows the full secret once.
export TRUTO_API_TOKEN="<paste-token-here>"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 loginYou'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--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 jsonwhoami 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 sitesset-keysaves to the profile-pnames (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:
--tokenflag (highest priority)- With
-p <name>: that profile'sapiToken, thenTRUTO_API_TOKEN. Without-p:TRUTO_API_TOKEN, then the active profile'sapiToken - Error if none found
API URL:
--api-urlflag- With
-p <name>: that profile'sapiUrl, thenTRUTO_API_URL. Without-p:TRUTO_API_URL, then the active profile'sapiUrl 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.
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 loginnever saves over it. - An empty file, or valid JSON with no
profileskey, counts as no profiles.truto loginthen writes the file. - Saves go through a temporary file and rename, so an interrupted save leaves the previous file in place.
- A
profilesentry 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
- Global options:
-p,--token, output formats - Managing integrations: first admin commands after login