Installing the SDK and running your first command

Prerequisites

Python >=3.13,<3.14
uv — the only supported package manager (never bare pip)
For provider-backed commands: a Modal account and either provider API keys or an Infisical project (see Secrets and API keys)

Get started

Clone

git clone <repository-url> gtm-sdk
cd gtm-sdk

Consuming the SDK from another project instead? See Installation.

Install dependencies

uv sync

Wire credentials for provider-backed commands

Commands that touch external providers (Exa, Attio, Apollo, Parallel, …) execute as functions on your Modal deployment — the CLI is a thin client that invokes them by name. Two things make those commands work:

A deployed app. Authenticate with Modal (uv run modal token new), then:
uv run modal deploy deploy.py

Provider keys. Pass them per command with API-key flags, or let the deployed functions fetch them from Infisical at entry:

# No Infisical required: pass the provider key directly on the command.
# The flag rides the call to the deployed Modal function and overrides
# the environment inside the container for that one invocation.
uv run gtm exa search "developer-first CRM tools" --exa-api-key <YOUR_EXA_API_KEY>

# One-time: copy the template and fill in your Infisical credentials.
cp .env.example .env.local

# Once per shell: load the bootstrap credentials.
set -a && source .env.local && set +a

# Keys are fetched from Infisical at function entry — no per-service flags.
infisical run --projectId "$INFISICAL_PROJECT_ID" --token "$INFISICAL_TOKEN" --env=prod -- \
  uv run gtm exa search "developer-first CRM tools"

The Secrets and API keys page explains the resolution order and the Infisical bootstrap in full.

Search your Attio workspace

Find a person in your CRM without changing any data (replace the example name):

uv run gtm attio people search --name "Ada Lovelace" --limit 10

Filter the people search to an email domain when you want to find everyone at a company:

uv run gtm attio people search --email-domain "acme.dev" --limit 10

Both commands return a JSON envelope with the matching records and a result count. You can also search by --email or browse records with --sample.

Quality gates

trunk check --all   # lint + type check
uv run pytest       # tests (integration tests excluded by default)

Next steps

Secrets and API keys

Key resolution order, Infisical bootstrap, and the env-var reference.

CLI contract

JSON on stdout, errors on stderr, preview-by-default mutations.

Architecture

The enforced cli → src → libs layering and where new code goes.

Telemetry

OTEL collector fan-out to Dash0, HyperDX, Logfire, and Grafana.

Get started

Concepts

Telemetry

Contributing

Changelog

Installing the SDK and running your first command

Prerequisites

Get started

Quality gates

Next steps

Secrets and API keys

CLI contract

Architecture

Telemetry

​Prerequisites

​Get started

​Quality gates

​Next steps

Secrets and API keys

CLI contract

Architecture

Telemetry

Prerequisites

Get started

Quality gates

Next steps