External Memory Series — File-based memory for AI-assisted work (overview · 1 Implementation · 2 Productivity · 3 vs the diagram · 4 Governance)

From Empty Folder to First Quality Score in 10 Minutes

If you are trying Gravio for the first time, speed matters. You want value fast, and you do not want onboarding confusion around project naming, repeated auth steps, or token placeholders.

This guide gives you the practical path from empty folder to first score.

The 3-Step Reality

A lot of tools overcomplicate onboarding. Gravio works best when you keep it simple:

1. Download CLI and run setup once.
2. Authorize the folder once with your user API key.
3. Run a local scan.

That is it.

Step 1: Download CLI and Setup

Windows:

1Invoke-WebRequest https://gravio.dev/cli/gravio.mjs -OutFile gravio.mjs2node gravio.mjs --setup --target .

macOS/Linux:

1curl -fsSL https://gravio.dev/cli/gravio.mjs -o gravio.mjs2node gravio.mjs --setup --target .

This prepares the folder so later scans are consistent.

Step 2: Authorize the Folder Once

1node gravio.mjs --authorize --target . --project <name> --server https://gravio.dev --api-key <YOUR_USER_KEY>

Important details:

1. API key is user-bound, not project-bound.
2. Authorization is one-time per folder, not every scan.
3. If the key auto-fill placeholder appears, hard-refresh while signed in.

Step 3: Run the First Scan

1node gravio.mjs --once --target .

What happens:

1. If this is a new project, Gravio creates it automatically.
2. If the project already exists, it appends a new run.
3. In cloud-only encrypted mode, you do not get a local plaintext scorecard file.

Common Setup Mistakes

Mistake 1: Treating project naming as a separate onboarding phase

It is not. First scan handles creation flow automatically.

Mistake 2: Re-authorizing on each scan

Authorization is folder-level setup. Repeating it adds noise and confusion.

Mistake 3: Debugging the wrong issue when token placeholder appears

Usually the fix is session state in browser, not CLI syntax.

Additional detail

What to Do After the First Score

Once you have your first run, do two things:

1. Establish a recurring scan cadence.
2. Decide how score thresholds should affect release confidence.

To understand why recurring scans matter, read Why AI Agent Output Quality Drifts Over Time.

To operationalize thresholds in pipelines, read The New CI Gate: Failing Builds on Agent Quality.

What is Gravio onboarding?

Gravio onboarding is a three-step local setup: download the CLI and run setup once, authorize the folder once with your user API key, then run a scan. First scan creates the project automatically if needed. Authorization is folder-level—not repeated every scan—so teams can establish a recurring quality cadence without auth friction.

TL;DR

• A practical, no-fluff walkthrough for getting Gravio running from a clean folder to your first quality score, including the exact command flow and common mistakes.

Reference

Quick reference: first-run command flow

Additional detail

Common mistakes (Gravio setup)

FAQ

How long does first score take?

About 10 minutes with a clean folder if API key and session state are ready—mostly download, authorize, and one scan.

Is the API key project-specific?

No. The key is user-bound. Project identity comes from folder authorization and scan context.

What happens on the first scan of a new project?

Gravio creates the project automatically and records the first run.

What should I do immediately after the first score?

Establish a recurring scan cadence and decide how thresholds affect release confidence—then read CI quality gates.

Does setup work the same on Windows and macOS?

Yes—download gravio.mjs, run setup, authorize, scan. Platform-specific fetch commands differ; flow is identical.

Why Fast Onboarding Is Strategic

Teams adopt what feels reliable and low-friction. A clear first-run experience turns quality tooling from "nice to have" into team habit.

Then habit becomes policy.

If you are evaluating Gravio from a security perspective, also read Zero-Knowledge AI Quality: How Gravio Scores Agents Without Seeing Your Code.

Do you want to join Gravio as a beta tester or support as an open source contributor? Simply sign up on gravio.dev and email me, I will convert your account to pro.