ThinkPlatform Client

ThinkPlatform Client provides the tp command-line interface and Python SDK for working with a ThinkPlatform service. Install it into a supported Python environment and connect it to a service URL and credentials supplied by your deployment.

Install

python -m pip install --upgrade pip
python -m pip install ThinkPlatform-client

The public binary wheels target CPython 3.11–3.13 on Linux x86_64 (glibc 2.28 or newer), macOS 11 or newer on Apple silicon (arm64), and Windows x86_64. Source distributions are not published. Other Python versions and platforms are outside the public wheel support matrix. Use a fresh virtual environment if migrating from a full ThinkPlatform runtime installation.

Command line

tp --help

Interactive profile setup guides a person through the connection and context choices without requiring them to look up organization or project IDs first. This command is not included in the published ThinkPlatform-client 0.6.103; the example below applies to a client build that includes the feature.

tp profile setup

The wizard asks for a profile name and connection defaults, authenticates with the configured credential, then lists accessible organizations and projects with numbered choices, names and IDs. Choose by number; the ID is shown only to help distinguish entries. After a summary and confirmation, the selected organization and project are saved in the named profile and that profile is activated. For example:

$ tp profile setup
Profile name [default]: staging
Base URL [https://thinkplatform.ai]:
Audience [api://04d6aecc-4540-463a-87e3-4024ffad7428]:
Auth mode [interactive-browser]:
Connecting to https://thinkplatform.ai using interactive-browser.
Organizations:
  1. Acme Research (ID: 42)
  2. Acme Sandbox (ID: 87)
Select organization: 1
Projects:
  1. Sensor project (ID: 301)
  2. Archive (ID: 318)
Select project: 1
Profile 'staging': https://thinkplatform.ai; interactive-browser; organization Acme Research (ID: 42); project Sensor project (ID: 301).
Save and activate this profile? [Y/n]: y

Entering staging creates or updates that target profile. An optional root --profile work supplies a different suggested profile name. The wizard resolves connection defaults for the target profile, rather than copying settings from whichever profile was previously active. Root CLI flags and environment variables continue to follow their usual precedence. Setup is interactive and requires a terminal; it rejects JSON output and --query before authentication or network access. Cancelling, an empty access list, or an authentication/API error leaves the saved configuration unchanged. The wizard makes read requests only; it does not create or modify service-side resources.

After setup, use ordinary commands with the active profile's saved connection, organization and project:

tp canvas pages list
tp canvas pages get <page_id>
tp mlops jobs list
tp db tables list

The default auto output uses readable tables, fields or text when possible, with JSON for complex payloads. No output flag is required. For machine-readable output or field extraction, opt in separately:

tp --json canvas pages list
tp --query user.username whoami

To switch saved profiles, use tp profile use staging. Root --profile, --org-id and --project-id flags are optional per-invocation overrides.

For agents and scripts, keep using the explicit, non-wizard commands. For example, inspect context with tp context orgs and tp context projects, then use tp configure --no-prompt with root --org-id and --project-id options. The existing tp configure prompt also remains available for offline setup of connection defaults without discovering organizations or projects.

With no deployment settings configured, the CLI uses https://thinkplatform.ai, API audience api://04d6aecc-4540-463a-87e3-4024ffad7428, and interactive-browser sign-in through a shared public client registration. The built-in tenant is 5a959e94-a278-467d-ab33-d59909a75bad; the built-in CLI application ID is 709439d2-4a99-44c2-8c35-9b1e71cc2e34. These are non-secret public application settings. Users do not need to register an app per installation or provide a client secret.

The registration is single-tenant, supports the http://localhost loopback redirect, and has device-code public-client flow enabled. Your organization may require administrator consent. A successful sign-in does not grant ThinkPlatform membership or resource permissions. The CLI uses the same REST client as the SDK.

For production browser/device authentication, the CLI stores tokens in the operating system's encrypted credential store and keeps a separate non-secret account record under ~/.config/thinkplatform/auth/. Later CLI processes reuse the account silently until Azure requires sign-in again. SDK client_from_profile() uses the same secure cache. If encrypted OS storage is unavailable, authentication fails closed without writing tokens in plaintext. On headless Linux without Secret Service, use Azure CLI authentication instead.

On macOS, this uses a dedicated ThinkPlatform CLI Keychain item. macOS may ask you to allow the Python interpreter to access it. A one-time permission can prompt again on later accesses; persistent permission is an optional trust decision for that interpreter. Changing Python installations can also require permission again. Older preview versions used a Microsoft shared item; the CLI does not read or migrate that item, so sign in again after upgrading if needed. Workspace managed-identity authentication does not use this local user cache.

Custom deployments and sign-in

For a different deployment, set its URL and API audience explicitly. An existing configured deployment that has no explicit auth mode continues to use azure-cli; use the mode approved for that deployment. These environment variables can be replaced by CLI options or a saved CLI profile:

export THINKPLATFORM_API_BASE_URL="https://thinkplatform.example"
export THINKPLATFORM_API_AUDIENCE="api://<api-application-id>"
export THINKPLATFORM_AUTH_MODE="azure-cli"
tp auth login

The examples use POSIX shell syntax; on PowerShell set environment variables with $env:NAME = "value". Azure CLI is a separate installation. Its credential uses the signed-in Azure CLI identity; the API must allow that identity and consent must permit access to its resource. Signing in alone does not establish service access. See Microsoft's Azure CLI credential documentation.

For browser or device-code sign-in to a different deployment, provide its approved public client application ID and tenant:

export THINKPLATFORM_AZURE_CLIENT_ID="<cli-public-client-application-id>"
tp --auth-mode device-code whoami
# Or, on a machine with a local browser:
tp --auth-mode interactive-browser whoami

Keep THINKPLATFORM_API_AUDIENCE configured for the target API. The API audience identifies the target API; THINKPLATFORM_AZURE_CLIENT_ID identifies the sign-in client. They serve different purposes. The CLI requests the API audience with /.default appended. Set the audience explicitly rather than relying on the legacy AZURE_CLIENT_ID audience fallback, which can accidentally target the sign-in client instead of the API.

The production CLI defaults apply only when the effective URL and audience are exactly https://thinkplatform.ai and api://04d6aecc-4540-463a-87e3-4024ffad7428, with browser or device-code auth selected. Explicit client ID and tenant environment variables override the built-in values. For custom URL/audience combinations, set the deployment's approved IDs yourself. Tenant lookup prefers THINKPLATFORM_AZURE_TENANT_ID over AZURE_TENANT_ID; client ID lookup prefers THINKPLATFORM_AZURE_CLIENT_ID over AZURE_CLIENT_ID. Client ID and tenant are read from the environment rather than stored in CLI profiles. The base URL, audience, auth mode, and connection settings can be selected through CLI flags or profiles.

For custom deployments, administrators should provision and validate a dedicated CLI public-client registration, configure its delegated API permissions and required tenant consent, and distribute the non-secret client ID, tenant and API audience to users. Users can share that approved registration; they do not need to create an app per installation. Choose the supported account/tenant configuration for the deployment. Do not distribute a client secret or reuse a confidential web application's credentials. Device-code sign-in requires public client flows to be enabled. Browser sign-in uses a local loopback redirect; this CLI leaves the port selection to Azure Identity, so configure http://localhost under the Mobile and desktop applications platform in the registration. See Microsoft's public-client setup guidance and desktop application configuration. A registration is ready for onboarding only after both the Entra configuration and API admission have been verified for that deployment.

workspace-delegation is for a provisioned workspace using managed identity and a workspace assertion; its optional client ID selects a user-assigned managed identity, not a desktop sign-in registration. execution-delegation uses an API-issued execution token bound to its service and org/project context. Obtain these configurations from the workspace or execution environment rather than setting a public-client ID for them.

Python SDK

from thinkplatform.sdk import ThinkPlatformClient
from thinkplatform.sdk.credentials import AzureCliCredential

client = ThinkPlatformClient(
    base_url="https://thinkplatform.example",
    audience="api://your-service",
    credential=AzureCliCredential(),
)

user = client.auth.whoami()
organizations = client.organizations.list()

The SDK also provides profile and environment based client factories, typed resource clients, and context helpers. Flow and Agent API operations are available without installing their execution engines.

Compatibility and security

The CLI and SDK are clients for an existing ThinkPlatform service; they do not include the service or grant access to it. The service remains responsible for authenticating requests and enforcing authorization. Cython wheels omit the original Python implementation files, but compiled code, names, documentation strings, and string constants can still be inspected. Do not treat the wheel format as a security boundary or put secrets in client code.