---
title: dashboards
description: Pull, validate, and save dashboards as JSON files.
canonical_url: https://orchestor.io/docs/en/cli/dashboards
markdown_url: https://orchestor.io/docs/en/cli/dashboards.md
contentType: reference
---

# dashboards

`orc dashboards list` lists dashboards. `get SLUG` reads a dashboard with its Spec v2. `pull` is an alias for `get`. Use `pull SLUG --raw --output dashboard.json` to save response data as JSON. Edit title or spec, check structure and metric catalog membership with `validate --stdin < dashboard.json`, then save a draft with `push SLUG --stdin < dashboard.json`. Viewers continue to see the published content. Review the draft with `pull SLUG --state draft --raw --output draft.json`, then publish with `publish SLUG --version VERSION` or discard with `discard SLUG --version VERSION`. Use the version returned by the draft pull. get/pull default to published state. A new slug creates an empty published dashboard and the pushed draft. Without a draft, pull --state draft returns 404 and publish/discard return 409. Files saved with `pull` include `version` to detect concurrent edits. Pull again after a 409 conflict caused by concurrent edits. Pushing a dashboard deleted since the pull returns 409. To recreate it, remove `version` from the file and push again. Omit `version` when creating a new dashboard. Saving identical content preserves version. `schema --raw` returns the Spec v2 JSON Schema. `schema` is a reserved slug for JSON Schema discovery. Standard input accepts JSON only; YAML input is not supported.

## Usage

```bash title="terminal"
orc dashboards list --workspace YOUR_WORKSPACE_ID --json
```

*List dashboards*

## Render

`orc dashboards render SLUG` executes published elements in layout order and returns each compiled MetricQuery and result. Use `--state draft` to render a draft; a missing draft returns 404. Results default to 20 rows per element; `--rows` accepts 1 to 10000. `row_count` counts rows returned by the engine before local truncation. `has_more` indicates local truncation or more upstream data. A failed element returns `error` while other elements continue. An element that fails compilation omits `query`. Use `--elements brands,visibility` to select names; results retain layout order. Unknown names return 400. For more data, run `orc dashboards render SLUG --elements brands --rows 10000 --workspace YOUR_WORKSPACE_ID --json`. You can also save one returned `query` as query.json and run `orc metrics query --workspace YOUR_WORKSPACE_ID --stdin < query.json`. Select fewer elements or rows if long strings or large results exceed the MCP response limit. Rendering returns data without generating images or PDFs.

## Templates

`orc dashboards templates --workspace YOUR_WORKSPACE_ID --json` lists all five templates with id, title, description, and Spec v2. This follows the existing single-level command convention. `orc dashboards create-from-template --template-id visibility-overview --workspace YOUR_WORKSPACE_ID --json` creates a published dashboard using the same conversion as the editor. `--title` defaults to the template title. `--slug overview` uses that exact slug or returns 409 if taken. Omit it to derive an available slug from the title. `schema`, `templates`, and `from-template` are reserved slugs. MCP tools are `render_dashboard`, `list_dashboard_templates`, and `create_dashboard_from_template`.

## Subcommands

### `list`

List dashboards

```bash title="terminal"
orc dashboards list [options]
```

### `schema`

Get dashboard Spec v2 JSON Schema

```bash title="terminal"
orc dashboards schema [options]
```

### `validate`

Validate a dashboard without saving

```bash title="terminal"
orc dashboards validate [options]
```

#### Unique options

##### `--spec`

(required) Body field: spec; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc dashboards validate --spec <value>
```

### `get`

Get a dashboard

```bash title="terminal"
orc dashboards get <slug> [options]
```

#### Unique options

##### `--state`

enum: published|draft

Type: `string`. Optional.

```bash title="terminal"
orc dashboards get <slug> --state <value>
```

### `push`

Create or update a dashboard draft by slug

```bash title="terminal"
orc dashboards push <slug> [options]
```

#### Unique options

##### `--spec`

(required) Body field: spec; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc dashboards push <slug> --spec <value>
```

##### `--title`

(required) Body field: title; max 120 chars

Type: `string`. Optional.

```bash title="terminal"
orc dashboards push <slug> --title <value>
```

##### `--version`

Body field: version

Type: `number`. Optional.

```bash title="terminal"
orc dashboards push <slug> --version <value>
```

### `discard`

Discard a dashboard draft

```bash title="terminal"
orc dashboards discard <slug> [options]
```

#### Unique options

##### `--version`

Body field: version

Type: `number`. Optional.

```bash title="terminal"
orc dashboards discard <slug> --version <value>
```

### `publish`

Publish a dashboard draft

```bash title="terminal"
orc dashboards publish <slug> [options]
```

#### Unique options

##### `--version`

Body field: version

Type: `number`. Optional.

```bash title="terminal"
orc dashboards publish <slug> --version <value>
```

### `create-from-template`

Create a published dashboard from a template

```bash title="terminal"
orc dashboards create-from-template [options]
```

#### Unique options

##### `--slug`

Body field: slug

Type: `string`. Optional.

```bash title="terminal"
orc dashboards create-from-template --slug <value>
```

##### `--template-id`

(required) Body field: template_id; enum: visibility-overview|citation-overview|competitive-proposal|content-opportunities|brand-perception

Type: `string`. Optional.

```bash title="terminal"
orc dashboards create-from-template --template-id <value>
```

##### `--title`

Body field: title; max 120 chars

Type: `string`. Optional.

```bash title="terminal"
orc dashboards create-from-template --title <value>
```

### `templates`

List dashboard templates

```bash title="terminal"
orc dashboards templates [options]
```

### `render`

Render dashboard element data

```bash title="terminal"
orc dashboards render <slug> [options]
```

#### Unique options

##### `--state`

enum: published|draft

Type: `string`. Optional.

```bash title="terminal"
orc dashboards render <slug> --state <value>
```

##### `--rows`

value

Type: `number`. Optional.

```bash title="terminal"
orc dashboards render <slug> --rows <value>
```

##### `--elements`

Comma-separated element names; results remain in layout order; max 5049 chars

Type: `string`. Optional.

```bash title="terminal"
orc dashboards render <slug> --elements <value>
```

### `pull`

Get a dashboard

```bash title="terminal"
orc dashboards pull <slug> [options]
```

#### Unique options

##### `--state`

enum: published|draft

Type: `string`. Optional.

```bash title="terminal"
orc dashboards pull <slug> --state <value>
```

## Examples

### Edit and save a file

```bash title="terminal"
orc dashboards pull overview --workspace YOUR_WORKSPACE_ID --raw --output dashboard.json
# Edit title or spec in dashboard.json
orc dashboards validate --workspace YOUR_WORKSPACE_ID --stdin < dashboard.json
orc dashboards push overview --workspace YOUR_WORKSPACE_ID --stdin < dashboard.json
orc dashboards pull overview --state draft --workspace YOUR_WORKSPACE_ID --raw --output draft.json
orc dashboards publish overview --version VERSION --workspace YOUR_WORKSPACE_ID
# orc dashboards discard overview --version VERSION --workspace YOUR_WORKSPACE_ID
```

*Edit and save a file*

## Permissions

Sign in and select a Workspace you can access. API keys need read scope for reads and validation, and write scope to push, publish, discard, and create from templates.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc dashboards`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

[Documentation index](https://orchestor.io/docs/llms.txt)