Skip to content

docs(clickstack): clarify dashboard validation and update bodies #741

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sdairs merged 1 commit into from
Sep 7, 2026
Merged

docs(clickstack): clarify dashboard validation and update bodies #741

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,9 +213,25 @@ broadcast selections, expose variables to tile queries, or do both:
}
```

Run `dashboard validate` before create or update to check the same dashboard body without saving it.
`dashboard update <service-id> <dashboard-id> --config-file dashboard.json` is a full PUT replacement:
include every tile, filter, container, tag, and saved query value that should remain.
`dashboard validate` checks a create body without saving it; it does not accept or validate an update body.
Dashboard updates use a separate full PUT body. Start from the complete current dashboard, preserve the
`id` of every existing filter, and include every tile, filter, container, tag, and saved query value that
should remain. For example, an existing filter entry in `dashboard-update.json` must retain its identity:

```json
{
"id": "<existing-filter-id>",
"name": "Service",
"expression": "ServiceName",
"sourceId": "<source-id>",
"type": "QUERY_EXPRESSION"
}
```

```bash
clickhousectl cloud clickstack dashboard update <service-id> <dashboard-id> \
--config-file dashboard-update.json --org-id <org-id>
```

Create a notification destination first, then reference its ID from an alert. For example,
`webhook.json` can contain a complete generic webhook body:
Expand Down
8 changes: 5 additions & 3 deletions crates/clickhousectl/src/cloud/clickstack.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -236,13 +236,14 @@ pub enum DashboardCommands {
#[command(after_help = "\
CONTEXT FOR AGENTS:
This is a full PUT replacement; include every required and desired field.
Every existing filter must retain its `id` in the request body.
Serialize edits to one dashboard; concurrent updates can overwrite each other.")]
Update {
/// Service ID (from `cloud service list`)
service_id: String,
/// Dashboard ID (from `cloud clickstack dashboard list`)
dashboard_id: String,
/// Complete JSON request body path, or `-` for stdin
/// Complete update JSON body path, or `-` for stdin
#[arg(long, value_name = "PATH|-", required = true)]
config_file: String,
/// Organization ID (auto-detected only if you have one org)
Expand All @@ -259,15 +260,16 @@ CONTEXT FOR AGENTS:
#[arg(long)]
org_id: Option<String>,
},
/// Validate a ClickStack dashboard without saving it
/// Validate a dashboard create body without saving it
#[command(after_help = "\
CONTEXT FOR AGENTS:
Accepts the create schema only; it does not validate update bodies.
Validation never persists the dashboard.
Uses API key authentication under the CLI's write-command policy.")]
Validate {
/// Service ID (from `cloud service list`)
service_id: String,
/// JSON request body path, or `-` for stdin
/// Dashboard create JSON body path, or `-` for stdin
#[arg(long, value_name = "PATH|-", required = true)]
config_file: String,
/// Organization ID (auto-detected only if you have one org)
Expand Down