@overscore/cli

Command line tool for Overscore — build a dashboard locally with your AI coding agent, deploy it with one command, share a secure URL with your team.

Install

Nothing to install. Everything runs via npx:

npx @overscore/cli auth login

That opens a browser, you approve the device, and credentials are saved to ~/.overscore/config. You never handle an API key. Devices are listed and revocable in the hub under Settings → Agents & devices.

Requires Node 18.17 or later.

Day to day

open is the usual starting point. It sets the project workspace up if you don't have it, fetches the selected dashboard, and hands your AI tool the outer workspace root so project rules, skills, catalog, dbt, and every dashboard remain in view:

npx @overscore/cli open sales-dashboard --project acme
npx @overscore/cli dev       # supervised dev server, temporary auth
npx @overscore/cli deploy    # build, upload, go live

This launches or instructs your normal Codex, Claude Code, VS Code, or terminal environment. Overscore does not replace its profile, plugins, MCP servers, hooks, or authenticated connectors.

dev supervises the local Vite process tree. It prefers port 5173 for compatibility, asks the OS for a free loopback port if that port is busy, and accepts --port N when you need an exact port. The ready URL is printed only after child-owned Vite output and a loopback Vite probe agree. Child output is credential-redacted. 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, but a native Job Object remains the gate for guaranteed cleanup after an already-exited root. Cleanup failures are reported, and the temporary development key is revoked or allowed to expire if revocation fails. This remains an explicitly trusted developer workflow because the project's package scripts and Vite configuration are ordinary local code.

Workspace registrations are isolated by Hub environment, signed-in account, and immutable project ID. The outer folder also carries a non-secret immutable identity marker; a remembered path alone is never enough to write into or launch an agent against a deleted-and-recreated folder. Existing workspaces are backfilled only after a local dashboard ID matches the authenticated project's Hub dashboard set. If home set or home forget would ambiguously hit an older slug-only record, the CLI stops and prints the exact identity-qualified repair command instead of claiming a repair that open would ignore.

Overscore-owned generated files use a canonical workspace boundary and atomic writes: a linked folder or config file cannot redirect a pull, sync, scaffold, dbt-pack, or catalog write into another project. Explicit external linked dbt projects still work, and these checks do not alter the agent's own profile, plugins, MCP servers, hooks, or connectors.

The machine config at ~/.overscore/config is likewise opened without following links and updated transactionally. Login and logout change only Overscore-owned authentication fields, preserving unrelated configuration and never treating a Claude, Codex, Gmail, or MCP profile as an Overscore file.

Pull preserves local agent state (.claude, .agents, .codex), connector variables in .env*, and Overscore machine state. It publishes downloaded source from a private stage, records the exact remote bytes as its baseline, and retains the prior managed source under .overscore/pull-recovery/. A save made by Codex, Claude Code, VS Code, or another editor while pull is running is therefore detected or recoverable rather than silently treated as remote code. Fresh pulls recreate generic Claude/Codex entrypoints from the installed CLI and authenticated platform context, so private instructions never have to be embedded in a source archive.

Inside an immutable outer workspace, deploy, pull, sync, and analysis publish bind mutable slugs to the registered project/dashboard/analysis IDs before any source is replaced or uploaded. Reusing an old slug therefore stops with a repair message instead of silently switching clients or artifacts.

Your dashboard lands at https://{project}.overscore.dev/{dashboard}/.

Commands

| Command | What it does | |---|---| | auth / auth login / auth logout | check, create, or remove saved credentials | | open <slug> --project <slug> | set up or fetch a dashboard and hand off the outer workspace root | | dev [--port N] | start a supervised loopback dev server with temporary auth | | deploy | build and deploy the dashboard | | promote / rollback | move a staged deploy live, or revert to a previous version | | versions | list deploy history | | pull <slug> | pull source code from the hub | | list / projects | list dashboards in the project, or every project on your account | | query <sub> | manage dashboard queries — list, add, update, remove, run | | analysis <sub> | manage analyses — new, publish, pull, preview | | platform <sub> | sync platform rules and capabilities | | home list/set/forget | inspect or repair local workspace registrations | | install agent-skill --claude\|--codex | merge-install the owned Overscore router skill without touching unrelated skills | | install-skills | deprecated alias for the ownership-safe global Overscore router install | | upgrade | update the CLI |

Add --json for machine-readable output.

Queries

Dashboard queries are registered with the hub and executed server-side, so warehouse credentials never reach the browser or ship in your bundle:

npx @overscore/cli query add revenue_by_month "SELECT ..."
npx @overscore/cli query run revenue_by_month

Read them in your dashboard with useQuery.

Targeting another environment

The CLI talks to overscore.dev by default. Set OVERSCORE_HUB_URL to point a terminal somewhere else. It is per-terminal on purpose — a fresh shell goes back to production.

Docs

• CLI reference
• Getting started
• Deploying
• overscore.dev

License

Proprietary. Part of the Overscore platform.