How Metricsjar connects your project

You are the coding agent onboarding the project in your current working directory. Metricsjar computes analytics locally with the user's own credentials and uploads only dashboard rows.

The user supplied a Pair token on a separate line. It works once and expires after 15 minutes. Never print it, commit it, or place it in the ledger.

1. Install and start

Read the CLI before running it if either you or the user wants to audit the single-file implementation.

mkdir -p ~/.metricsjar
curl -fsSL https://www.metricsjar.com/cli.ts -o ~/.metricsjar/cli.ts
curl -fsSL https://www.metricsjar.com/cli.sha256 -o /tmp/metricsjar-cli.sha256
(cd ~/.metricsjar && shasum -a 256 -c /tmp/metricsjar-cli.sha256)
bun ~/.metricsjar/cli.ts version
bun ~/.metricsjar/cli.ts onboard <PAIR_TOKEN>

If Bun is missing, install it with the project's normal package-management policy. Do not ask the user to run shell commands.

onboard exchanges the one-time token, creates a resumable local setup record, and inspects the repo. Once the project is registered, Metricsjar opens the real dashboard. Missing metrics show —; Pipe health is the only visible setup status.

2. Inspect once, then report once

Determine the production domain or app identifier from the repo and deployment configuration. Re-run the probe with every confirmed value you can discover:

bun ~/.metricsjar/cli.ts onboard inspect \
  --domain <domain> \
  --gcloud-account <confirmed-email> \
  --bq-project <project-if-known> \
  --gsc-dataset <dataset-if-known> \
  --ga4-dataset <dataset-if-known>

Do not make the user classify the project as existing, partial, or new. Metricsjar classifies each source independently as found, needs setup, needs instrumentation, needs approval, warming, optional, or broken.

Probe silently, then give the user one compact report:

• what already works;
• what Metricsjar will reuse;
• what needs setup or instrumentation;
• what is optional;
• the decisions only they can make.

3. Ask only at real checkpoints

Continue through ordinary reversible setup work under the user's onboarding request. Interrupt only for:

1. Identity — name the exact Google account and target project. Never choose between personal, work, or client accounts yourself. Pin Google commands with CLOUDSDK_CORE_ACCOUNT; never change the global gcloud account.
2. Billing — immediately before linking the named billing account to the named GCP project. State that BigQuery may incur usage charges.
3. Paid enrichment — before the first DataForSEO spend. Give the expected cost and number of tracked terms.

If authentication has expired, provide the exact deep link or login action. If a console or DNS account is ambiguous, stop before changing it.

4. Route source by source

Read the machine-readable references/source-registry.json, then use:

• Existing sources: verify the selected account can read them, register them, refresh, and install the scheduler.
• Partial sources: repair only the missing link, IAM grant, dataset, key, or scheduler-visible credential.
• Uninstrumented web products: follow references/website-onboarding.md.
• Native/mobile products: follow references/app-onboarding.md. Treat Search Console as a source for the marketing website, not the native binary.

Enable Search Console bulk export as soon as the domain is known. It has no API and no backfill. Prepare its IAM roles and dataset before the console click. GA4's BigQuery export also has no backfill.

Register a correctly configured source before its first tables appear. Empty exports with verified access and IAM are yellow/warming, not broken.

5. Keep the setup session current

Use these commands after interruption or whenever the plan changes:

bun ~/.metricsjar/cli.ts onboard status
bun ~/.metricsjar/cli.ts onboard continue

Every material action needs a setup event containing the result, evidence, and undo operation when one exists. Keep secrets out. For full instrumentation, also keep the redacted repository ledger required by the relevant runbook.

bun ~/.metricsjar/cli.ts onboard event \
  --title "<what changed>" --type "<source>" --status ok \
  --detail "<result>" --evidence "<ids or verification>" --undo "<undo>"

When a checkpoint needs the user, publish the exact account/project, financial effect, and deep link. Resume it after their answer:

bun ~/.metricsjar/cli.ts onboard needs-user --message "<brainless action>"
bun ~/.metricsjar/cli.ts onboard resume

6. Completion contract

Finish only after:

• the project is visible in the requested Metricsjar account;
• every configured pipe is green or yellow/warming, with no red rows;
• tracked keywords are loaded when requested;
• the first dashboard refresh has published;
• doctor --as-cron passes;
• the scheduler is loaded.

Run the final gate:

bun ~/.metricsjar/cli.ts onboard verify <slug>

That command records the scheduler-mode doctor evidence, marks the setup live, and prints the dashboard URL. Open the dashboard for visual verification before reporting completion.