cube-run-query
Run queries against a Cube deployment's semantic layer and interpret the results — through the Cube MCP tools when they are connected, or the Cube CLI from a terminal. Use whenever someone wants numbers out of Cube — pull a metric, check a total, compare periods, verify that a measure returns what it should, sanity-check a model change. Triggers on "how many", "what's the total", "show me revenue by month", "did that measure work", "what's our MoM growth", "pull the numbers for", and any request to verify a model change against real data. To find out what is queryable first use cube-explore-model; to change the model use cube-build-model; to save a result as a report or dashboard use cube-build-content.
How do I install this agent skill?
npx skills add https://github.com/cube-js/cube-agent-skills --skill cube-run-queryIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates querying Cube deployments using the official Cube CLI and curl. It includes a preflight check to install the Cube CLI tool from the vendor's official GitHub repository if it is not already present in the environment.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Run a query against Cube
Choose the path
Cube MCP tools are written cube:<tool> below: the cube server this plugin
bundles. Through the Cube connector, the same tools carry the connector's name.
If the Cube MCP tools are available, use them. They come from this
plugin's cube server or the Cube connector — look for cube:searchDataModel,
cube:runQuery and cube:chat. They need no install or login step, and every call runs
as the signed-in user, so row-level security applies exactly as in the UI.
- A specific number:
cube:searchDataModelto find the view and the exact member names, thencube:runQuerywith Cube SQL —SELECT status, MEASURE(count) FROM orders_view GROUP BY 1. Never guess a member name. - An open-ended question ("why did signups drop in March"):
cube:chat, which runs Cube's own agent over the governed model and existing reports. Give the user thecubeChatUrlit returns so they can continue in Cube. - Another deployment:
cube:listDeployments, then pass itsdeploymentId. - A dev branch: pass the same
branchNametocube:searchDataModelandcube:runQuery, so the members you find are the ones the query sees. - More than 100 rows: page
cube:runQuerywithoffsetuntilhasMoreis false.
Use the CLI path below when the MCP tools are not connected, or in a script or CI job. Interpreting results applies to both paths.
CLI path
Querying steps outside the CLI. cube api is bound to Cube's console API
and cannot reach a deployment's query endpoint, so querying is two CLI calls
to get a URL and a token, then a direct request to the deployment.
Preflight
command -v cube >/dev/null || echo "Cube CLI not installed: curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh"
cube whoami || echo "Not authenticated. Interactive: cube login. Headless: set CUBE_API_URL + CUBE_API_KEY."
cube context list
jq and curl are also required here, unlike every other skill in this
plugin. Check for them and say so if they are missing.
Get the endpoint and a token
DEPLOYMENT=<id>
URL=$(cube deployments get "$DEPLOYMENT" --json | jq -r .deploymentUrl)
TOKEN=$(cube deployments token "$DEPLOYMENT")
cube deployments token prints the Cube API token on its own; add --json
if you want the wrapping object. The token carries the calling user's
security context, so row-level security applies exactly as it would in the
UI — a query here returns what that user is allowed to see, not everything.
Know what you can query first
Do not guess member names. Ask the compiled model:
cube meta --selectors '[{"type":"cube","deploymentId":'"$DEPLOYMENT"',"environment":"production"}]'
Members are Cube.member or View.member. A dimension that exists on a cube
but is not exposed in a view is not queryable through that view — cube meta
is what tells you which is which.
Run it
curl -s "$URL/cubejs-api/v1/load" \
-H "Authorization: $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"query":{
"measures":["Orders.count","Orders.totalRevenue"],
"dimensions":["Orders.status"],
"timeDimensions":[{"dimension":"Orders.createdAt","granularity":"month","dateRange":"Last 6 months"}],
"limit":100
}}' | jq
Query shape, in the order you usually need it:
measures— the numbers. Always fully qualified.dimensions— what to break down by.timeDimensions—dimensionplusgranularity(day/week/month/…) anddateRange, which accepts natural ranges like"Last 30 days"or an explicit["2026-01-01","2026-06-30"].filters—[{"member":"Orders.status","operator":"equals","values":["paid"]}].order,limit.
The response carries data plus annotation, which holds the human titles
and formats for each member. Use annotation when presenting results — it is
where a measure's display name and unit live.
Interpreting results
- Report the number, then how it was derived. Which measure, which range, which filters. A number without its query is not checkable.
- An empty
dataarray is a result, not an error. Say the query succeeded and returned no rows; do not retry with a different query and present that instead without saying you changed it. - Never fill in a value you did not receive. If the query failed, report the error.
Verifying a model change
The common case after cube-build-model: query the new measure on the dev
branch before merging. Over MCP, pass the dev branchName to
cube:searchDataModel and cube:runQuery. With the CLI, $URL/cubejs-api/v1/load
always answers from production; a dev branch has its own endpoint under the
same deployment URL, used with the same token:
cube deployments build-status "$DEPLOYMENT" --branch <dev-branch> --wait
curl -s "$URL/dev-mode/<dev-branch>/cubejs-api/v1/load" -H "Authorization: $TOKEN" ...
Point cube meta at the branch the same way, with "environment":"<dev-branch>".
When something fails
| Symptom | Cause |
|---|---|
deploymentUrl is null | The deployment has never finished a build; check cube deployments build-status |
| 401 from the load endpoint | Token expired — they are short-lived, just mint another |
Member not found | Wrong name or not exposed in that view — re-check cube meta, do not guess a variant |
{"error":"Continue wait"} | The query is still running — send the same request again until data comes back. Tell the user if it keeps going past a minute or two |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/cube-js/cube-agent-skills/cube-run-query">View cube-run-query on skillZs</a>