CLI

sumcli — Summation’s command-line client for scripting, automation, and agent workflows over the public API.

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.

Building an interactive agent experience? The Claude plugin and MCP server are the easier path. Reach for sumcli when you’re scripting, running in CI, or driving Summation from your own automation.

Install

sumcli installs into its own isolated environment with pipx, so it lands on your PATH without touching any project’s virtualenv. It requires Python 3.11+.

Contact your Summation representative for the current install package. Once installed, verify:

sumcli --help

Sign in

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

Device login (people)

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

auth login opens a browser approval — the same device sign-in the plugin uses. No secrets are entered on the command line.

Machine-to-machine (automation)

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 login --m2m
sumcli auth whoami | jq .

Your Summation admin issues the client_id and client_secret. Ideal for CI and unattended jobs.

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
SUMCLI_OUTPUT=human sumcli projects list # always human view

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

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.

Inspect, attach, and query

A freshly imported table lives in your workspace grid but isn’t attached to a project yet. Attach it to make it 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

Ask Addison and generate reports

sumcli chats create --wait
sumcli reports generate --wait
sumcli reports verify --wait

Long-running commands (chats create, chats reply, reports generate, reports verify, tables import) support --wait / --no-wait, and --follow where applicable.

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/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 <id>	Set 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/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.