CLI Reference

The Navieo CLI scans your codebase, generates the sitemap, and pushes everything to Navieo's backend for embedding and indexing.

Installation

npm install -D @navieo/cli

Commands

navieo init

Scan your codebase and generate the initial sitemap and docs folder.

npx navieo init

What it does:

1. Detects your framework (Next.js App Router, Pages Router, or Vite)
2. Scans all routes in your project
3. Extracts interactive elements (buttons, links, inputs) from each route
4. Generates navieo/sitemap.navieo.json with discovered routes and elements
5. Creates navieo/docs/ folder with a starter doc template
6. Adds navieo/.last-sync.json to .gitignore

Options:

Output files:

navieo/
  sitemap.navieo.json   # Your app's route and element map
  docs/
    getting-started.md    # Starter documentation template

Note: navieo init won't run if a navieo/ folder already exists. Use navieo generate to update an existing sitemap.

navieo generate

Re-scan your codebase and update the existing sitemap without losing manual edits.

npx navieo generate

What it does:

1. Re-scans your codebase for routes and elements
2. Intelligently merges new scan results with your existing sitemap:
   • Preserves manually-written descriptions and custom routes
   • Updates selectors from the latest source code
   • Adds newly discovered routes
   • Keeps flows and docs untouched
3. Writes the merged result back to navieo/sitemap.navieo.json

Options:

This is safe to run repeatedly — it won't overwrite your manual work.

navieo fix

Add data-navieo-id attributes to interactive elements that have weak selectors. This improves tour reliability by giving the AI high-confidence selectors to find elements in the DOM.

npx navieo fix

What it does:

1. Scans your codebase for interactive elements (buttons, links, inputs, etc.)
2. Identifies elements with low or medium confidence selectors (class-based, structural)
3. Generates deterministic data-navieo-id values from element text, name, or placeholder
4. Shows a preview of proposed changes
5. On confirmation, inserts data-navieo-id attributes directly into your source files

Options:

Example output:

Scanning codebase for weak selectors...
✓ Detected framework: nextjs-app
✓ Scanned 12 routes across 34 files

Found 47 elements with weak selectors:
  23 low confidence (class-based)
  24 medium confidence (semantic CSS)

Proposed changes:
  app/page.tsx
    L12  <button>  → data-navieo-id="button-get-started"
    L28  <a>       → data-navieo-id="link-pricing"
  app/dashboard/page.tsx
    L15  <input>   → data-navieo-id="input-search"
    L33  <button>  → data-navieo-id="button-submit"

Apply 47 changes across 12 files? [Y/n]

✓ Added data-navieo-id to 47 elements across 12 files

Run navieo generate to update your sitemap with the new selectors.

Notes:

• Idempotent — running twice produces no changes on the second run
• Preserves formatting — only the data-navieo-id attribute is inserted; no other changes to your code
• Skips elements that already have data-navieo-id, id, or aria-label (already high confidence)
• After running fix, run navieo generate && navieo push to update your sitemap with the new selectors

navieo push

Upload your sitemap and docs to Navieo's backend for embedding and indexing. Automatically pulls the latest cloud state first to detect conflicts.

npx navieo push

What it does:

1. Pulls the latest dashboard docs from the cloud (auto-pull) and checks for conflicts
2. Reads navieo/sitemap.navieo.json and all files in navieo/docs/
3. Parses markdown docs into sections (split on ## headings)
4. Applies visibility rules from .navieorc (if present), including docsExclude patterns
5. POSTs everything to Navieo's backend
6. Backend chunks the data, generates embeddings, and stores them in pgvector
7. Saves a local snapshot (.last-sync.json) for change tracking

Options:

API key resolution (in priority order):

1. --key flag on the command line
2. NAVIEO_SECRET_KEY environment variable
3. apiKey field in .navieorc

Example:

# Using env var (recommended)
NAVIEO_SECRET_KEY=nv_secret_your_key_here npx navieo push

# Using --key flag
npx navieo push --key nv_secret_your_key_here

# Using .navieorc (key is read automatically)
npx navieo push

Example output:

Pulling latest from cloud before push...
✓ Pull complete — 2 new, 0 conflicts

✓ Loaded sitemap: 10/10 routes, 0 flows
✓ Loaded 2 doc files (6 sections)

Pushing to https://api.navieo.io...
✓ Push complete
  Routes: 10 | Docs: 2 | Chunks: 42 | Embedded: true

Important: Each push is a full replacement — all existing embeddings for your app are deleted and regenerated from scratch. This ensures your search index always matches your current sitemap exactly.

Dry Run

Preview what a push would upload without actually sending anything:

npx navieo push --dry-run

Example dry-run output:

✓ Loaded sitemap: 10/10 routes, 0 flows
✓ Loaded 2 doc files (6 sections)

Dry run — changes that would be pushed:

Docs:
  ~ accounts.md
  + transfers.md

Summary: 1 doc modified, 1 doc added

Run navieo push to apply these changes.

The dry-run flag does not require an API key, so you can preview changes before configuring authentication.

navieo pull

Download the latest docs and flows from the cloud to your local project.

npx navieo pull

What it does:

1. Fetches the latest docs and flows from Navieo's backend
2. Detects changes using a 3-way merge (snapshot hash vs local hash vs cloud hash)
3. Writes new and updated docs to navieo/docs/
4. Merges flow changes into navieo/sitemap.navieo.json
5. Reports any conflicts (docs only — flows use cloud-wins strategy)

Options:

Merge behavior:

• Docs: 3-way merge with conflict detection. If both local and cloud modified the same doc since the last sync, the local version is kept and the conflict is flagged for manual resolution.
• Flows: Cloud wins. If local and cloud flows differ, the cloud version overwrites the local version. The dashboard is the source of truth for flows.

Example output:

Pulling from https://api.navieo.io...

New docs (from dashboard):
  + billing.md

Updated docs (cloud changed):
  ↓ getting-started.md

Updated flows (cloud changed):
  ↓ Onboarding

✓ Pulled 1 new doc, 1 updated doc, 1 updated flow.

navieo status

Show route visibility and doc sync status with change tracking.

npx navieo status

What it shows:

• Routes classified by visibility: indexed, not indexed, widget hidden, excluded
• Docs with sync state: synced, modified, new, excluded, or deleted
• Change summary since last sync (if a snapshot exists)

Options:

Example output:

Navieo Route Status

Patterns from .navieorc:
  exclude: /api/*
  docsExclude: internal-*.md

Indexed (will be embedded and widget visible):
  ✓ /dashboard
  ✓ /accounts
  ✓ /accounts/[id]
  ✓ /transfers
  ✓ /settings

Excluded (not synced, AI won't know about these):
  ✗ /api/health

────────────────────────────────────────
Total: 6 routes | Indexed: 5 | Excluded: 1

Docs:
  ✓ getting-started.md   (4 sections)  — synced
  ~ accounts.md           (3 sections)  — modified
  + transfers.md          (2 sections)  — new
  ✗ internal-notes.md     (1 section)   — excluded
  - old-faq.md                          — deleted (will be removed on next sync)

────────────────────────────────────────
Last synced: 2026-03-01 12:34 to api.navieo.io
Changes since last sync: 1 doc modified, 1 doc added, 1 doc deleted

Doc sync states:

Change Tracking

The CLI tracks what was synced by saving a local snapshot file (navieo/.last-sync.json) after each successful sync. This file is automatically added to .gitignore — it's local state, not committed to your repo or sent to the backend.

The snapshot stores content hashes (not full copies) for each route and doc. This allows navieo status and navieo push --dry-run to detect what changed since the last push without needing to query the backend.

Workflow:

# 1. Push your sitemap and docs
npx navieo push

# 2. Make changes (edit docs, run navieo generate, etc.)

# 3. Check what changed
npx navieo status

# 4. Preview what the next push would do
npx navieo push --dry-run

# 5. Push the changes
npx navieo push

Handling Deletions

If you delete a doc file or a route disappears after running navieo generate, the next push will remove it from the backend (since the backend does a full replacement).

• navieo status shows deleted items with a - prefix so you know what will be removed
• navieo push --dry-run previews removals before they happen
• No special "undelete" or "untrack" command is needed — just recreate the file

Configuration: .navieorc

You can optionally create a .navieorc file in your project root to configure the CLI. This is not created by navieo init — you only need it if you want to persist settings like your API endpoint, exclude routes, hide the widget on specific pages, or exclude docs from sync.

{
  "apiKey": "nv_secret_your_key_here",
  "endpoint": "https://api.navieo.io",
  "exclude": ["/admin/*", "/internal/*"],
  "widgetHidden": ["/login", "/signup"],
  "docsExclude": ["internal-*.md", "draft-*.md"]
}

Patterns use glob syntax — * matches any single path segment, ** matches any depth.

Resolution Priority

The CLI resolves apiKey and endpoint from multiple sources. Higher priority wins:

API Key:

Endpoint:

Security tip: For CI/CD pipelines and team projects, use the NAVIEO_SECRET_KEY environment variable instead of putting your API key in .navieorc. If you do use .navieorc for the key, make sure the file is in your .gitignore.

Visibility Fields

When to use exclude: Routes like /admin/* or /api/* that you don't want the AI to know about or guide users through.

When to use widgetHidden: Routes like /login or /signup where the chat widget should not appear, but the AI can still reference them in tours.

When to use docsExclude: Internal documentation, drafts, or notes in navieo/docs/ that you don't want embedded into the AI's knowledge base. The files stay on disk — they're just filtered out of the sync payload.

Typical Workflow

# 1. First time: scan and generate
npx navieo init

# 2. Edit the generated sitemap — add descriptions, flows, docs
#    (see Sitemap Configuration docs)

# 3. Push to Navieo
NAVIEO_SECRET_KEY=nv_secret_your_key_here npx navieo push

# 4. After code changes: update sitemap
npx navieo generate

# 5. Check what changed
npx navieo status

# 6. Preview the push
npx navieo push --dry-run

# 7. Re-push
npx navieo push

Framework Support

The CLI automatically detects your framework and adjusts scanning accordingly. It resolves TypeScript path aliases from your tsconfig.json and follows component imports to find nested interactive elements.