> ## Documentation Index
> Fetch the complete documentation index at: https://summation-676748f5-docs-api-and-integrations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/integrations/public-api) and emits agent-friendly JSON, making it the right tool for scripted automation and headless agent workflows.

<Note>
  Building an interactive agent experience? The [Claude plugin](/integrations/claude-plugin) and [MCP server](/integrations/mcp-server) are the easier path. Reach for `sumcli` when you're scripting, running in CI, or driving Summation from your own automation.
</Note>

## Install

`sumcli` installs into its own isolated environment with [pipx](https://pipx.pypa.io), 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:

```bash theme={null}
sumcli --help
```

## Sign in

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

<Tabs>
  <Tab title="Device login (people)">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Machine-to-machine (automation)">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## 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:

```bash theme={null}
sumcli --output json projects list      # always JSON
SUMCLI_OUTPUT=human sumcli projects list # always human view
```

<Warning>
  The human view is lossy — wide tables drop columns. Never parse it. Pipe the JSON output through `jq` for anything scripted.
</Warning>

## Common workflows

### Load a local CSV into a table

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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
```

<Warning>
  **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.
</Warning>

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](/integrations/public-api).