CLI Reference

The Overscore CLI handles scaffolding new dashboard projects and deploying them to your secure URL. Everything runs via npx — no global install required.

create-overscore

Scaffold a new dashboard project with everything wired up and ready to go.

npx create-overscore

Interactive prompts

The scaffolder asks you a few questions:

1. Project directory — where to create the project (default: ./my-dashboard)
2. Project slug — your Overscore project slug (e.g., acme)
3. Dashboard slug — a name for this dashboard (e.g., sales-dashboard)
4. Login — the first run opens your browser to sign in. After that the saved credentials are reused, and you are not asked again on that machine. You never handle an API key.

What it creates

my-dashboard/
├── src/
│   ├── App.tsx            # Main dashboard component
│   ├── main.tsx           # Entry point with OverscoreProvider
│   ├── queries/
│   │   └── index.ts       # Query definitions for registration
│   └── components/        # Starter chart components
├── public/
├── .env                   # Project and dashboard config
├── package.json           # Dependencies pre-configured
├── vite.config.ts         # Vite build config
└── tsconfig.json

The generated project includes @overscore/client as a dependency and sets up the OverscoreProvider with your project and dashboard slugs.

Flags

| Flag | Description | |------|-------------| | --name <dir> | Project directory name (skips the prompt) | | --project <slug> | Project slug (skips the prompt) | | --dashboard <slug> | Dashboard slug (skips the prompt) |

Example with all flags:

npx create-overscore --name sales --project acme --dashboard sales-dashboard

overscore commands

Everything else runs through npx @overscore/cli. Sign in once per machine, then run any command from your dashboard folder.

npx @overscore/cli auth login

That opens a browser, you approve the device, and the credentials are saved to ~/.overscore/config. You can see and revoke your devices in the Hub at /settings/devices.

| Command | What it does | |---------|--------------| | auth | Check authentication status | | auth login | Authenticate via browser (one time per machine) | | auth logout | Remove saved credentials | | open <slug> --project <slug> | Set up or fetch a dashboard and hand your AI tool the outer project workspace | | dev [--port N] | Start a supervised loopback dev server with temporary auth | | list | List all dashboards in the project | | projects | List every project on your account | | deploy | Build and deploy the dashboard | | pull <slug> | Pull source code from the hub | | versions | List deploy history | | query <subcommand> | Manage dashboard queries (list/add/update/remove/run) | | platform <subcommand> | Sync platform rules and capabilities | | analysis <subcommand> | Manage analyses (new/publish/pull/preview) | | home list/set/forget | Inspect or repair local workspace registrations | | install agent-skill --claude\|--codex | Merge-install the owned Overscore router skill without changing unrelated agent integrations | | install-skills | Deprecated broad skill-library installer |

open <slug> --project <slug> is the usual starting point for day-to-day work. It sets the project workspace up if you don't have it yet, fetches the selected dashboard, and opens or prints the outer workspace root. That root is where project rules, skills, catalog, dbt, and all dashboards live. Your normal Codex, Claude Code, VS Code, or terminal profile—and its unrelated plugins, MCP servers, hooks, and connectors—continues to work normally.

Local registrations are isolated by Hub environment, account, and immutable project ID. Ambiguous slug-only home repairs stop with an exact identity-qualified command rather than changing a different client's folder.

The CLI requires Node 18.17 or later. It checks on startup and prints a clear message on older versions.

overscore deploy

Build and deploy your dashboard to Overscore.

npx @overscore/cli deploy

What it does

1. Builds your React app using Vite (runs npm run build)
2. Bundles the output from dist/ into a deployment package
3. Uploads the package to Cloudflare R2 storage via POST /api/deploy
4. Stages or activates the version according to the dashboard's deploy-review setting

The CLI prints the result explicitly. A direct deploy is available at the live URL; a staged deploy includes a private preview and leaves the current live version unchanged until you run promote or use Go live in the Hub.

https://{project-slug}.overscore.dev/{dashboard-slug}/

Flags

| Flag | Description | |------|-------------| | --message <text> | Add a description to the deployment history | | --live | Skip a configured staged-preview step and send this version directly to viewers | | --force | Override the stale-folder drift guard after reviewing the conflict | | --no-source | Upload the built dashboard without its source snapshot |

Example

# Standard deploy
npx @overscore/cli deploy

# Add a deployment note
npx @overscore/cli deploy --message "Tighten the forecast filters"

# Deliberately skip the staged preview
npx @overscore/cli deploy --live

The target project and dashboard come from the workspace configuration written by overscore open, pull, or the scaffolder. Open the intended dashboard workspace before deploying; deploy does not accept project or dashboard override flags.

npm run queries

Register your dashboard's queries with the Hub so they can be executed server-side.

npm run queries

This script reads the query definitions from src/queries/index.ts and pushes them to the Hub. Each query specifies:

• queryName — unique identifier used by useQuery in your dashboard code
• sql — the BigQuery SQL to execute
• description — optional, shown in the Hub UI

You need to run this whenever you add or modify queries. Queries must be registered before they'll work in a deployed dashboard.

Example query definition

// src/queries/index.ts
export const queries = [
  {
    queryName: "revenue_by_month",
    sql: `
      SELECT
        FORMAT_DATE('%Y-%m', order_date) AS month,
        SUM(revenue) AS total_revenue
      FROM \`my-project.analytics.orders\`
      GROUP BY month
      ORDER BY month
    `,
    description: "Monthly revenue totals"
  },
  {
    queryName: "top_customers",
    sql: `
      SELECT customer_name, SUM(revenue) AS lifetime_value
      FROM \`my-project.analytics.orders\`
      GROUP BY customer_name
      ORDER BY lifetime_value DESC
      LIMIT 20
    `,
    description: "Top 20 customers by lifetime value"
  }
];

Environment variables

Your .env file configures the CLI and client package:

| Variable | Description | Example | |----------|-------------|---------| | VITE_OVERSCORE_PROJECT_SLUG | Your project slug, read by Vite at build time | acme | | VITE_OVERSCORE_DASHBOARD_SLUG | This dashboard's slug, read by Vite at build time | sales-dashboard | | VITE_OVERSCORE_API_URL | The Hub API this dashboard talks to | https://overscore.dev/api |

These are set automatically by create-overscore. The VITE_ prefix ensures Vite exposes them at build time. The slugs are used by both the CLI (for deployment) and the client package (for query routing).

There is no API key in .env. npx @overscore/cli dev mints a short-lived key itself and injects it into the trusted local dev server as VITE_OVERSCORE_API_KEY. The CLI prefers port 5173, selects a free loopback port when it is occupied, and also accepts an exact --port N. It waits for child-owned Vite output plus a loopback Vite probe and redacts the temporary key from child output. POSIX shutdown verifies that the detached process group is gone. Windows makes bounded taskkill /T and /T /F passes while the root PID is still addressable; a native Job Object remains required to guarantee cleanup after an already-exited root. Cleanup failures are reported, and the key is revoked or allowed to expire if revocation fails. deploy runs the production build with that variable set to an empty string, so no key ships in the deployed bundle. A deployed dashboard authorizes its queries with the viewer's own signed access token instead.

Do not commit .env to version control. The scaffolder adds it to .gitignore by default.

Next steps

• Getting Started — full walkthrough from sign-up to deploy
• Authentication — how CLI login and dashboard access work
• Data Caching — speed up your dashboards with Parquet caching