Skip to main content
Connect tp to the ThinkPlatform deployment you use, then verify the account and project before working with resources. Start with the installation guide if tp --help is not available yet.

​
Set up a profile

For a person at a terminal, start with:
The wizard asks for a profile name, service URL, API audience and authentication mode. Review the defaults, complete sign-in, choose an accessible organization and project by number, and confirm the summary. Names are shown alongside IDs for disambiguation; you do not need to find IDs beforehand. Setup saves and activates the named profile only after confirmation.
Cancelling, an empty access list, or an authentication/API error leaves the saved configuration and active profile unchanged. Discovery uses reads and does not create or change service resources. Sign-in can still use the existing secure credential cache described below. Setup requires interactive input and output terminals. It rejects JSON output and root --query before authentication or network access. Agents and unattended scripts should use prepared profiles or the manual context commands, with configure --no-prompt when saving explicit settings. configure remains available for offline connection setup.

​
Get your connection settings

For the production service, tp profile setup guides browser sign-in and project selection. If your profile is already configured, use tp auth login to sign in again. The shared registration is already configured, so you do not need to create an app or provide a secret. Your organization may require administrator consent. If an approval request appears, follow your organization’s approval process and retry sign-in after it is approved.
These shared public-client defaults apply when the effective URL and audience match the production values and browser or device-code auth is selected. Environment variables and explicit CLI options can override them. If another URL or audience is configured without an explicit auth mode, the CLI uses azure-cli. Use the URL, audience, client ID, tenant, and auth mode approved for a custom deployment.
The https://thinkplatform.example and api://YOUR_API values below are placeholders for a custom deployment. Replace them with its actual settings.

​
Choose an authentication mode

The deployment must allow the application identity used by your chosen mode. Browser and device-code sign-in need an approved public-client registration; a web-only application registration is not sufficient. Administrator consent for one API audience does not grant access to a different API audience. For azure-cli, sign in through Azure CLI as directed by your administrator before running tp auth login. This mode uses Azure CLI’s application identity rather than the shared ThinkPlatform CLI registration, so the deployment must explicitly allow Azure CLI. For workspace delegation, use the settings injected by the workspace rather than copying credentials from another session.

​
Sign in separately or use a custom deployment

1

Set application settings for browser or device-code sign-in

Skip this step for the production defaults. For a custom deployment, use the approved public-client ID and tenant. You can also set THINKPLATFORM_AZURE_CLIENT_ID and THINKPLATFORM_AZURE_TENANT_ID to override the production registration. These environment settings are non-secret and are not stored in profiles.Bash
PowerShell
For custom deployments, set the API audience for the target service separately from the client ID used to sign in. Never use a client secret with these public-client flows.
2

Log in and save your connection defaults

For the production defaults, sign in using your active profile:
For a custom deployment, supply its URL and audience explicitly. Put global options before the command:
Choose device-code or azure-cli as the --auth-mode value when appropriate. Complete any sign-in prompts yourself. Login acquires a credential, calls the service to check your identity, and saves effective connection and context settings to the selected profile after success. For production browser/device flows, it also stores an encrypted token cache in the operating system’s credential store and a separate non-secret account record locally. Later CLI processes reuse that account silently while the stored credential remains valid; Azure may request sign-in again when required.
3

Verify the account and effective context

auth whoami makes an authenticated request to the service. Confirm it shows the intended account. context show displays effective local settings; it does not prove that you can access the selected project. Follow Select a context to discover organizations and projects and choose one you can access.

​
Configure without signing in

configure saves defaults without authenticating. Run it interactively to review the selected profile’s settings:
To save connection settings without prompts:
configure --reset-context clears saved organization/project defaults when writing configuration. Review the effective context again before continuing.

​
Work with profiles

Profiles keep connection and default context settings for different environments. Configuration is written to ~/.config/thinkplatform/config.json, unless THINKPLATFORM_CONFIG_PATH selects another file.
profile use changes the active saved profile. Successful profile setup, login and configuration also make their selected profile active. A profile is a set of settings; switching it does not sign out of Azure or revoke a credential. Profile selection uses --profile, then THINKPLATFORM_PROFILE, then the active saved profile (or default). Switching profiles changes connection settings; it does not switch the signed-in Azure account. Individual settings use explicit global flags first, environment variables second, and the selected profile third: With no deployment configured, the CLI uses its production service URL and audience defaults. If you configure another URL or audience, provide the matching deployment settings; an unspecified auth mode then resolves to azure-cli. Workspace delegation requires an explicit, environment-provided, or profile API URL. Environment overrides can remain effective after switching profiles, so check context show whenever you change environments.

​
Hand sign-in back to a person

When an agent reaches an interactive sign-in prompt, have a person complete it through the normal browser or device-code flow. Resume the task after checking auth whoami and the intended context. Do not paste passwords, access tokens, workspace assertions, or credential files into prompts or documentation. The Python SDK can use the same credential modes. See SDK authentication and the authentication command reference.

​
Secure credential persistence

CLI profiles store connection and context settings, not access tokens. Production browser/device credentials use an encrypted operating-system token cache and a separate non-secret account record at ~/.config/thinkplatform/auth/thinkplatform-cli-{hash}.json, where hash is the SHA-256 of the lowercase tenant ID, a colon, and the lowercase client ID. The CLI never stores tokens in plaintext. Removing this account record removes metadata only; it does not revoke or clear the cached session in the operating system’s credential store. Treat identity output as account information and review it before sharing logs. Production browser and device-code authentication requires OS-backed encrypted credential storage. The CLI fails closed when that storage is unavailable and does not write tokens in plaintext. On headless Linux systems without Secret Service, use Azure CLI authentication if your deployment allows Azure CLI:

​
Troubleshooting

For the production URL and audience, the shared registration is selected automatically unless client or tenant environment variables override it. For a custom deployment, set THINKPLATFORM_AZURE_CLIENT_ID and THINKPLATFORM_AZURE_TENANT_ID to its approved values. AZURE_CLIENT_ID and AZURE_TENANT_ID are accepted as fallbacks. Confirm custom deployment settings with its administrator before retrying.
The production browser and device-code flows need Linux Secret Service for encrypted token storage. On a headless system without it, use az login and --auth-mode azure-cli if your deployment allows Azure CLI, as described above. The CLI does not fall back to storing tokens in plaintext.
macOS may ask the Python interpreter running tp to access the login Keychain for the ThinkPlatform CLI encrypted token cache. Allow grants access for the current request, so the prompt may appear again. Always Allow is optional; choose it only if you recognize and trust that exact Python interpreter. Changing or upgrading the interpreter can trigger another prompt. Your Keychain password stays on your Mac; never share it in chat.If access is denied or the Keychain is locked, sign-in fails and the CLI does not store tokens in plaintext. Managed Agent Workspace managed-identity sign-in does not use your local user Keychain. Older Microsoft.Developer.IdentityService items are not read, migrated, or deleted by this CLI flow.
Inspect tp profile show and tp context show, then check environment overrides and any explicit global flags. For Azure CLI mode, confirm the account selected in Azure CLI. Run tp auth whoami again against the intended service, then select an accessible project using the context guide.
Confirm you are in the provisioned workspace with its expected API URL and context. Missing or expired assertions, missing workspace settings, managed identity configuration, or unavailable permissions need attention from the workspace administrator. Do not substitute credentials from another workspace.
Authentication identifies the caller; access still depends on the service’s permissions and selected organization/project. Confirm the account and context, then ask your administrator for the access required by the specific operation.