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> | Set up or fetch a dashboard and open it in your AI tool | | dev | Start the dev server (injects auth automatically) | | 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) | | install-skills | Install the Overscore skill library |

open <slug> is the usual starting point for day-to-day work. It sets the folder up if you don't have it yet, fetches the latest source if you do, and opens the dashboard in your AI tool.

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. Activates the deployment on the Cloudflare Worker

Once complete, your dashboard is live at:

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

Flags

| Flag | Description | |------|-------------| | --project <slug> | Override the project slug from .env | | --dashboard <slug> | Override the dashboard slug from .env | | --skip-build | Upload the existing dist/ folder without rebuilding |

Example

# Standard deploy
npx @overscore/cli deploy

# Deploy with overrides
npx @overscore/cli deploy --project acme --dashboard sales-q1

# Redeploy without rebuilding
npx @overscore/cli deploy --skip-build

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 dev server as VITE_OVERSCORE_API_KEY, so it only ever exists for local development. 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