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 and the per-endpoint pages under the Dashboards group for full request/response shapes.

Subcommands

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

list

List dashboard views for the configured pixel.

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.

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.

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 instead unless you have a specific configuration to load (e.g. exported from another pixel).

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.

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.

upstack dashboard view copy 5f1e6a4f-...

delete

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

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

upstack dashboard view section list 5f1e6a4f-...

section add

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

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

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.

section reorder

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

upstack dashboard view section reorder 5f1e6a4f-... <section-id> --to 0

section collapse / expand / hide / unhide

Toggle the display state of a section.

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

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.

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 instead to move widgets in and out of the Pinned section.

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.

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.

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