CLI

sumcli is Summation’s first-party command-line client. It talks to the stable /v1 routes of the Public API 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:

curl -fsSL https://install.summation.com/sumcli | sh

Then verify, and upgrade later with:

sumcli --help
uv tool upgrade summation-cli

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 — the same device sign-in the plugin uses. No secrets are entered on the command line.

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`)

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

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.

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)

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.

Get started

Features

API & Integrations

API Reference

Install

Resources

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`)

Working with profiles

Configuration reference

​Install

​Sign in

​Resources

​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)

​Working with profiles

​Configuration reference

Install

Sign in

Resources

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`)

Working with profiles

Configuration reference