> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summation.com/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.

## Install

Requires [uv](https://docs.astral.sh/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.

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

```bash theme={null}
curl -fsSL https://install.summation.com/sumcli | sh
```

Then verify, and upgrade later with:

```bash theme={null}
sumcli --help
uv tool upgrade summation-cli
```

## Sign in

`sumcli` stores credentials in profiles in `~/.summation/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` 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.
  </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 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.
  </Tab>
</Tabs>

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

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

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

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

<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

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

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

**Two-step** (when you want the CSV in the project file tree too):

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

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

```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
sumcli catalog detach --confirm file-...                       # remove the catalog entry
sumcli tables delete --confirm tbl-...                         # remove from grid
```

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

### Ask Addison and generate reports

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

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

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