> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# upstack dashboard view

> Manage Upstack dashboard views from the command line — list, show, create, update, copy, delete, organize widgets into sections, pin KPIs, and the high-level preset builder.

Manage Upstack dashboard views from the command line. Wraps the `/api/dashboard/views/*` endpoints — see the [API reference](/api-reference/overview) and the per-endpoint pages under the **Dashboards** group for full request/response shapes.

## Subcommands

| Subcommand                       | Wraps                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------- |
| [`list`](#list)                  | `GET /api/dashboard/views`                                                   |
| [`show <id>`](#show)             | `GET /api/dashboard/views/{id}`                                              |
| [`build`](#build)                | `POST /api/dashboard/views/from-preset`                                      |
| [`create --from-file`](#create)  | `POST /api/dashboard/views`                                                  |
| [`update <id>`](#update)         | `PATCH /api/dashboard/views/{id}`                                            |
| [`copy <id>`](#copy)             | `POST /api/dashboard/views/{id}/copy`                                        |
| [`delete <id>`](#delete)         | `DELETE /api/dashboard/views/{id}`                                           |
| [`section …`](#sections)         | `GET` + `PATCH /api/dashboard/views/{id}` (mutates `configuration.sections`) |
| [`pin <id> <widgetId>`](#pins)   | `PATCH /api/dashboard/views/{id}` (adds widget to Pinned section)            |
| [`unpin <id> <widgetId>`](#pins) | `PATCH /api/dashboard/views/{id}` (removes from Pinned section)              |

## list

List dashboard views for the configured pixel.

```bash theme={null}
upstack dashboard view list
upstack dashboard view list --type view              # default
upstack dashboard view list --type attribution_view
```

## show

Fetch a single view with its full configuration as JSON.

```bash theme={null}
upstack dashboard view show 5f1e6a4f-...
```

## build

The high-level builder — pass a list of measures, get a finished dashboard with auto-laid-out sparkline tiles. The most common command for AI agents and quick "give me a dashboard with these KPIs" workflows.

```bash theme={null}
upstack dashboard view build \
  --name "NC + Meta Pulse" \
  --measures core.new_customer_roas,core.new_customer_mer,meta.cpm
```

Optional flags:

| Flag                                                | Description                                          | Default             |
| --------------------------------------------------- | ---------------------------------------------------- | ------------------- |
| `--chart-types <c1,c2,...>`                         | One chart type per measure (positional pairing).     | `sparkline` for all |
| `--type <t>`                                        | `view`, `attribution_view`, or `pnl_view`.           | `view`              |
| `--layout <l>`                                      | Auto-layout strategy. Only `kpi-grid` today.         | `kpi-grid`          |
| `--attribution-model <m>`                           | `first_click`, `last_click`, or `any_click`.         | `first_click`       |
| `--attribution-window <days>`                       | Attribution lookback.                                | `30`                |
| `--granularity <g>`                                 | `day\|hour\|week\|month\|...`                        | `day`               |
| `--date-start <YYYY-MM-DD> --date-end <YYYY-MM-DD>` | Date range.                                          | last 30 days        |
| `--from-file <path>`                                | JSON file with any of the above. CLI flags override. |                     |

The CLI resolves each measure's friendly `shortTitle` from `GET /api/measures` (cached) before posting, so widget titles read nicely in the web app.

## create

Advanced — create a view from a full `DashboardViewConfiguration` body. Use [`build`](#build) instead unless you have a specific configuration to load (e.g. exported from another pixel).

```bash theme={null}
upstack dashboard view create --from-file ./my-view.json
```

The file must contain `{ type, name, configuration, order? }`.

## update

Partial update — only fields you pass are changed.

```bash theme={null}
upstack dashboard view update 5f1e6a4f-... --name "Renamed"
upstack dashboard view update 5f1e6a4f-... --order 3
upstack dashboard view update 5f1e6a4f-... --from-file ./partial.json
```

## copy

Duplicate a view.

```bash theme={null}
upstack dashboard view copy 5f1e6a4f-...
```

## delete

Delete a view. Prompts for confirmation; `--yes` skips the prompt.

```bash theme={null}
upstack dashboard view delete 5f1e6a4f-... --yes
```

## Sections

A view's widgets are grouped into **sections** — labelled blocks the web app renders with a header, optional collapse/hide, per-section density/pacing overrides, and a chosen layout mode. The CLI exposes every section operation the web app supports.

Every `section` subcommand follows a `GET → mutate → PATCH` flow internally: it fetches the view's current configuration, applies the mutation locally, then sends the full new configuration back via `PATCH /api/dashboard/views/{id}`. You don't need to construct the JSON yourself.

### section list

Print the sections in a view as a table (id, ordinal, layout mode, widget count, title, flags like `pinned` / `hidden` / `collapsed`).

```bash theme={null}
upstack dashboard view section list 5f1e6a4f-...
```

### section add

Create a new section. By default, appends to the bottom of the non-pinned sections.

```bash theme={null}
upstack dashboard view section add 5f1e6a4f-... --title "Performance"
upstack dashboard view section add 5f1e6a4f-... --title "Top KPIs" --position top
upstack dashboard view section add 5f1e6a4f-... --title "Detail" --after <existing-section-id>
```

| Flag                     | Description                                                     | Default       |
| ------------------------ | --------------------------------------------------------------- | ------------- |
| `--title <title>`        | Section title.                                                  | `New Section` |
| `--position top\|bottom` | Where to insert among non-pinned sections.                      | `bottom`      |
| `--after <sectionId>`    | Insert immediately after this section (overrides `--position`). |               |

### section rename / clone / delete

```bash theme={null}
upstack dashboard view section rename 5f1e6a4f-... <section-id> --title "Renamed"
upstack dashboard view section clone  5f1e6a4f-... <section-id>
upstack dashboard view section delete 5f1e6a4f-... <section-id>
```

`clone` deep-copies the section's widgets with fresh ids and appends the new section directly after the source. `delete` migrates any widgets from the deleted section into the first remaining non-pinned section so widgets aren't lost. The Pinned section can't be renamed, cloned, or deleted directly — it's managed via [`pin`/`unpin`](#pins).

### section reorder

Move a non-pinned section to a 0-based position among the other non-pinned sections.

```bash theme={null}
upstack dashboard view section reorder 5f1e6a4f-... <section-id> --to 0
```

### section collapse / expand / hide / unhide

Toggle the display state of a section.

```bash theme={null}
upstack dashboard view section collapse 5f1e6a4f-... <section-id>
upstack dashboard view section expand   5f1e6a4f-... <section-id>
upstack dashboard view section hide     5f1e6a4f-... <section-id>
upstack dashboard view section unhide   5f1e6a4f-... <section-id>
```

`collapse` keeps the header but hides the section's widgets. `hide` removes the entire section from rendering (config is preserved).

### section layout

Set the section's layout mode. Accepted values: `auto`, `1_column`, `2_columns`, `3_columns`, `4_columns` (matches the backend enum exactly; the CLI lowercases input so capitalization in your shell is fine).

```bash theme={null}
upstack dashboard view section layout 5f1e6a4f-... <section-id> --mode auto
upstack dashboard view section layout 5f1e6a4f-... <section-id> --mode 2_columns
```

### section density / pacing

Per-section overrides for density (`compact` or `normal`) and pacing. Pass `inherit` (density) or `--inherit` (pacing) to clear the override and fall back to view-level `defaultSettings`.

```bash theme={null}
upstack dashboard view section density 5f1e6a4f-... <section-id> --density compact
upstack dashboard view section density 5f1e6a4f-... <section-id> --density inherit

upstack dashboard view section pacing 5f1e6a4f-... <section-id> --enabled
upstack dashboard view section pacing 5f1e6a4f-... <section-id> --disabled
upstack dashboard view section pacing 5f1e6a4f-... <section-id> --inherit
```

### section move-widget

Move a widget from its current section into another non-pinned section. Use [`pin`/`unpin`](#pins) instead to move widgets in and out of the Pinned section.

```bash theme={null}
upstack dashboard view section move-widget 5f1e6a4f-... <widget-id> --to <target-section-id>
```

### section migrate

Legacy views created before sections were introduced have a flat `configuration.widgets` array and no `configuration.sections`. Run `migrate` to wrap those widgets in a single `Main` section so the CLI's other section commands can operate on them.

```bash theme={null}
upstack dashboard view section migrate 5f1e6a4f-...
```

Safe to call on views that already have sections (no-op).

## Pins

Pinning copies a widget into a dedicated **Pinned** section that always renders first in the view (it has `ordinal: -1` and `sectionType: "PINNED"`). The Pinned section is created on the first `pin` and removed when its last widget is unpinned — you never create or delete it yourself.

```bash theme={null}
# Pin: creates a fresh copy in the Pinned section with a new widget id.
# The copy carries `sourceWidgetId` linking it back to the original.
upstack dashboard view pin 5f1e6a4f-... <widget-id>

# Unpin: accepts either the pinned copy's id, or the original widget's id.
# The Pinned section is removed once its last widget is unpinned.
upstack dashboard view unpin 5f1e6a4f-... <widget-id>
```

Pinning the same widget twice is rejected — call `unpin` first if you want to re-pin a modified original.