CLI

sumcli is Summation’s first-party command-line client and the shortest path to everything in this tab. It talks to the stable /v1 routes of the API, manages token exchange and refresh for you, and emits agent-friendly JSON, making it the right tool for scripted automation and headless agent workflows.

Install

Requires uv and Python 3.11+ (uv can install Python for you). Installs into an isolated tool environment so sumcli lands on your PATH without touching any project’s virtualenv.

uv tool install summation-cli          # latest
uv tool install summation-cli==X.Y.Z   # or pin a release

Or bootstrap uv and install in one shot. Pick the command for your shell (don’t paste curl | sh into PowerShell or cmd.exe):

# macOS / Linux / Git Bash / WSL
curl -fsSL https://install.summation.com/sumcli | sh

# Windows PowerShell / pwsh
irm https://install.summation.com/sumcli.ps1 | iex

REM Windows cmd.exe (same installer, launched via PowerShell)
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://install.summation.com/sumcli.ps1 | iex"

Then verify, and upgrade later with:

sumcli --help
sumcli update

sumcli update installs the latest PyPI release, including over an exact-version pin. It refuses to run on a copy it doesn’t manage (NOT_UV_MANAGED). If you installed via brew, pip, or pipx, upgrade with that same installer instead so you don’t end up with two copies. Commands also print a once-a-day stderr notice when a newer release exists (stdout stays clean JSON); disable with SUMCLI_NO_UPDATE_CHECK=1.

The Claude and Codex plugins prefer sumcli whenever a shell is available and check the installed version at session start, so if you use the plugins, you may already have it.

sumcli stores credentials in profiles in ~/.summation/summation-config. Create a profile, then authenticate.

Device login (people)
Machine-to-machine (automation)

sumcli config set-profile work --base-url https://api.summation.com
sumcli config use work
sumcli auth login
sumcli auth whoami | jq .

auth login prints a device code and a URL. Approve it in the browser. No secrets are entered on the command line. This CLI session is separate from the plugins’ MCP browser approval: being signed in on one does not sign in the other.

sumcli config set-profile ci \
  --base-url https://api.summation.com \
  --client-id "$SUM_API_CLIENT_ID" \
  --client-secret "$SUM_API_CLIENT_SECRET"
sumcli config use ci
sumcli auth whoami | jq .
sumcli projects list | jq '.result.projects'

Your Summation admin issues the client_id and client_secret. Ideal for CI and unattended jobs: M2M credentials on the profile are enough; no separate login step.

Pin a default project per profile so project-scoped commands need no --project:

sumcli config set-project --profile work --project prj-...
sumcli config clear-project --profile work   # undo

Resources

Resource	Description
`auth`	Authentication state (`whoami`, `status`, `token`, `login`, `logout`)
`config`	Profiles, active session, and `~/.summation/summation-config`
`tenant`	Organization and tenant metadata
`projects`	Project CRUD and `current`
`chats`	Addison conversations; SSE → NDJSON with `--follow` on create/reply
`reports`	Generate and verify reports (`.sdoc`)
`playbooks`	Playbook discovery
`files`	Project-scoped files (`upload`, `download`, `list`, `show`, `import`, `delete`)
`filesystem`	Connected filesystem roots such as SharePoint
`catalog`	Project catalog entries (`list`, `show`, `attach`, `detach`, `refresh`)
`connections`	External data source connections (CRUD, `test`, `browse`)
`tables`	Grid tables and CSV import; also `append`, `data`, `import-status`
`views`	Summation views (`list`, `show`, `data`, `delete`)
`grid`	Grid `status`, `create`, `push`, `diff`, `validate`, `materialize`, `lineage`
`queries`	Read-only SQL execution (`queries run`)
`verification-tests`	Validate/upload custom tests, manage scoped overlays, and preview the effective set

Bare invocation prints the live command tree. Resource names and actions come from the installed CLI:

sumcli | jq '.result.resources'
sumcli projects --help   # per-command flags

Manage custom verification tests (sumcli 0.1.6+)

Validation is offline and uses the same canonical contract as the API. Mutating dry runs also stay offline: they emit the exact request but neither authenticate nor send it.

sumcli verification-tests validate --bundle ./deck-tests.yaml
sumcli verification-tests upload --bundle ./deck-tests.yaml --dry-run
sumcli verification-tests upload --bundle ./deck-tests.yaml
sumcli verification-tests list --subject-type deck --count 50

sumcli verification-tests attach \
  --scope project --subject-type deck --op add --custom-test-id cvt-...
sumcli verification-tests list-attachments --scope project --subject-type deck
sumcli verification-tests preview --scope project --subject-type deck
sumcli verification-tests detach vta-... --scope project --confirm

Use the cvt-... definition id returned by upload or list as --custom-test-id. Project scope uses the profile’s default project when --project is omitted. A cross-org call adds --target-org organization-live-... and must name --project explicitly; operator identity remains the signed-in user. --op remove --target-ref ... creates a removal overlay, while detach removes an existing attachment by its vta-... id.

Output for agents and scripts

When stdout isn’t a terminal (piped, captured, or run by an agent), sumcli emits JSON envelopes with contextual next_actions, and NDJSON for streaming commands. At an interactive terminal it renders a human-readable view instead. Force either mode explicitly:

sumcli --output json projects list       # always JSON; --output precedes the subcommand
SUMCLI_OUTPUT=human sumcli projects list # always human view; env var works in any position

The human view is lossy: wide tables drop columns. Never parse it. Pipe the JSON output through jq for anything scripted.

Common workflows

Load a local CSV into a table

Two ways: a one-shot direct ingest, or an explicit two-step that goes through the project file tree first. One-shot (recommended when you don’t need the file in the project tree):

sumcli tables import --local --path ./Customers.csv --table customers

Uploads the file, detects the schema, and materializes a new grid table. Outputs NDJSON ending in importStatus: SUCCESS with the new tbl-... ID. Two-step (when you want the CSV in the project file tree too):

# 1. Upload the CSV into the project at /Customers.csv.
sumcli files upload ./Customers.csv

# 2. Promote it from the project tree into the grid.
sumcli tables import --remote --path /Customers.csv --table customers

Step 2 also accepts --file-id file-... if you have the ID directly. If the file is already in the project (uploaded by someone else, dropped via the UI, etc.):

sumcli files list | jq '.result.files[] | select(.fileName | endswith(".csv"))'
sumcli tables import --remote --path "/Order_Details.csv" --table order_details

Inspect, attach, query, and clean up

A freshly imported table lives in the tenant grid but is not attached to the project catalog. Attach it to make it visible in catalog list and queryable as a project resource:

sumcli tables show tbl-...                                     # schema and columns
sumcli tables data tbl-... | jq '.result.data.rows[:5]'        # sample rows
sumcli catalog attach --source-type table --source-id tbl-...  # link to current project
sumcli catalog list                                            # confirm it's linked
sumcli catalog detach --confirm file-...                       # remove the catalog entry
sumcli tables delete --confirm tbl-...                         # remove from grid

tables delete removes the underlying grid table but does not auto-cascade the project catalog entry that referenced it. Detach the entry separately with catalog detach file-... --confirm.

Ask Addison and generate reports

sumcli chats create -m "hello"
sumcli reports generate -m "Q4 summary"
sumcli reports verify --wait

Long-running commands (`--wait` / `--follow`)

chats create, chats reply, reports generate, reports verify, grid push, and tables import all support --wait / --no-wait (and --follow where applicable).

Flag	Meaning
`--wait` (default)	Run to completion, then print the final envelope
`--no-wait`	Run to completion without printing progress
`--follow`	Print NDJSON progress while the operation runs (requires `--wait`)

All of those commands default to --wait. reports generate and reports verify also default to --follow; the rest default to --no-follow. --no-wait --follow is rejected (INVALID_FLAGS, exit 1).

sumcli reports generate -m "Q4 summary"              # wait, NDJSON stream (default follow)
sumcli reports generate -m "Q4 summary" --no-follow  # wait, single JSON response
sumcli reports generate -m "Q4 summary" --no-wait    # no progress, final envelope only
sumcli chats create -m "hello"                       # wait, single JSON response (follow off)
sumcli chats create -m "hello" --follow              # wait, NDJSON stream

tables import takes --wait / --no-wait but has no --follow; it streams NDJSON whenever it waits.

Stating intent (agents)

When an agent runs sumcli on a person’s behalf, it should pass the human’s request, in their own words and not a summary of the command, so downstream events can be joined to a goal:

sumcli --intent "convert my weekly recap" projects list   # root option, precedes the subcommand
export SUMCLI_INTENT="convert my weekly recap"            # or once per session

Requires sumcli ≥ 0.1.4. The value is normalized to one line and capped at 500 bytes after encoding; an oversized value is refused (INTENT_TOO_LONG). Omitting it never fails: machine-mode runs print a one-line stderr warning and continue, so unattended pipelines are unaffected. Discovery, --help, --version, update, and the auth, config, and filesystem groups never warn. SUMCLI_NO_INTENT=1 is an org-level kill switch: the header is never sent, even when an intent is set. Agent hosts can also identify their surface with a short product token (never free text):

export SUMCLI_CLIENT_CONTEXT="claude-plugin/1.1.0"   # appended to the User-Agent; analytics only

Working with profiles

Each profile pairs an API host with credentials and session state. Switch the active profile, or select one per command:

sumcli config use work                     # set the active profile
sumcli --profile work projects list        # one-off; --profile precedes the subcommand
export SUMMATION_PROFILE=work              # per-process, safe for parallel jobs

Running parallel agents or jobs? Don’t call config use against a shared ~/.summation/summation-config: the switch is global. Instead pass --profile on each command, or set SUMMATION_PROFILE in each subprocess.

Useful config commands:

Command	Description
`config list`	List profiles (secrets never shown)
`config active`	Show the resolved active profile, account, and default project
`config set-profile`	Create or replace a profile
`config use <profile>`	Set the active profile (optionally `--project`)
`config set-project --profile <name> --project <id>`	Set the default project for a profile
`config clear-project --profile <name>`	Clear the default project for a profile

Configuration reference

sumcli reads settings with field-specific precedence: CLI flags win, then environment variables, then the config file.

Variable	Purpose
`SUMMATION_CONFIG_FILE`	Path to the TOML config (default `~/.summation/summation-config`)
`SUMMATION_PROFILE`	Active profile name
`SUMMATION_PROJECT`	Default project ID when the profile sets none
`SUM_API_BASE_URL`	API host
`SUM_API_CLIENT_ID` / `SUM_API_CLIENT_SECRET`	M2M credentials
`SUM_API_ACCESS_TOKEN`	Static bearer token (skips the M2M exchange)
`SUM_API_M2M_SCOPE`	Scopes requested in the M2M exchange
`SUMCLI_OUTPUT`	Force `json` or `human` output in any position
`SUMCLI_NO_UPDATE_CHECK`	Skip the daily PyPI version check
`SUMCLI_INTENT`	Session-wide intent string (see Stating intent)
`SUMCLI_NO_INTENT`	Never send the intent header, even when one is set
`SUMCLI_CLIENT_CONTEXT`	Calling-surface token appended to the User-Agent (analytics only)

Identity always comes from the bearer token. sumcli never trusts caller-supplied identity headers. For the underlying endpoints and error conventions, see the Public API.

Introduction

Resources

Endpoints

Install

Resources

Manage custom verification tests (sumcli 0.1.6+)

Output for agents and scripts

Common workflows

Load a local CSV into a table

Inspect, attach, query, and clean up

Ask Addison and generate reports

Long-running commands (`--wait` / `--follow`)

Stating intent (agents)

Working with profiles

Configuration reference

​Install

​Sign in

​Resources

​Manage custom verification tests (sumcli 0.1.6+)

​Output for agents and scripts

​Common workflows

​Load a local CSV into a table

​Inspect, attach, query, and clean up

​Ask Addison and generate reports

​Long-running commands (--wait / --follow)

​Stating intent (agents)

​Working with profiles

​Configuration reference

Install

Sign in

Resources

Manage custom verification tests (sumcli 0.1.6+)

Output for agents and scripts

Common workflows

Load a local CSV into a table

Inspect, attach, query, and clean up

Ask Addison and generate reports

Long-running commands (`--wait` / `--follow`)

Stating intent (agents)

Working with profiles

Configuration reference