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. API key — your project's API key (find it in Hub under Settings)

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                   # API key and project 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 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_API_KEY | Your project's API key, read by Vite at build time | os_live_abc123... | | 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 |

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

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

Next steps