Naar
Menu
Docs

Use Naar quickly, then go deeper only where it matters

Naar has three distinct moves: search for discovery, go for repo-guided selection, and install for explicit writes. This page is the fastest path to understanding that model.

Getting started

If you only remember one thing: search is read-only discovery, go is repo-guided discovery, and install is the only write path.

Mental model

Two doors lead into the same safe installer. Use naar search when you already know the kind of skill you want. Use naar go when you want Naar to infer what fits the current repository.

1. Search

Browse provider catalogs directly and copy an explicit skill reference.

2. Go

Scan the repo, fetch candidates, rank them, and review what fits.

3. Install

Fetch the selected bundle, run content checks, preview writes, and confirm.

Installation

Naar runs on Node.js and can be installed globally or used directly with npx.

CLI

Global install

Best for regular use. The command stays short and predictable.

npm i -g naar-cli

Ephemeral

No global install

Useful for quick trials, CI, or one-off runs.

npx -y naar-cli@latest naar go

Prerequisite

Naar requires Node.js >=20. If the CLI behaves unexpectedly, check your local Node version first.

Two ways to use Naar

Choose the door that fits your current task. The distinction matters because it keeps discovery fast without weakening install review.

Search-first

Use this when you already know the theme of the skill you want: testing, GitHub Actions, React, security, docs, deployment.

  • Does not scan the repo.
  • Does not install anything by itself.
  • Returns install-ready refs such as clawhub:brewpage.

Repo-guided

Use this when repo context matters more than the exact skill name. Naar will detect stack, tools, assistants, and readiness before ranking skills.

  • Scans local files for structured facts.
  • Fetches provider candidates and ranks fit.
  • Leads into the same reviewed install flow.

Search workflow

Search behaves more like npm search than a recommender. It is a catalog lookup with provider-aware result formatting.

Direct search 

$ naar search "github actions"
1. brewpage [clawhub]
Install: naar install clawhub:brewpage

What search is for

  • Browsing provider catalogs directly.
  • Finding explicit install refs without recommendation overhead.
  • Comparing publisher, license, freshness, and skill page URLs.

Basic search

naar search "github actions"

Alias

naar s "design"

Automation output

naar search "next" --json

Guided `go` workflow

`naar go` is the fastest way to answer: what belongs in this repo, for these assistants, and what will it write?

  1. 1. Scan the repository for languages, frameworks, tools, project shape, and assistant readiness.
  2. 2. Fetch provider candidates and reuse repo needs for broader retrieval.
  3. 3. Rank candidates by fit while keeping trust and risk separate.
  4. 4. Select skills and targets interactively.
  5. 5. Install through the same post-fetch security and plan review path.
Guided flow 

$ naar go
[1/5] Scan
[2/5] Providers
[3/5] Recommendations
[4/5] Selection
[5/5] Install

Install workflow

Install is shared by both entry points and remains explicit even when the rest of the flow is automated.

Preview before writing

Dry runs show the install plan without touching the repo.

naar install clawhub:brewpage --dry-run

Direct install

When you already know the ref, install it directly without scanning the repo.

naar install clawhub:brewpage

What always happens in install

Fetched bundles are analyzed again at install time. Naar builds a write plan, surfaces conflicts, and requires confirmation before writing managed files.

Common commands

These are the commands you are most likely to use after the first install.

Use case Command What it does
Guided flow `naar go` Scan the repo, fetch providers, rank matches, and move into the reviewed install flow.
Direct discovery `naar search "github actions"` Search provider catalogs directly without scanning the repo or installing anything.
Explicit install `naar install clawhub:brewpage --dry-run` Fetch one explicit skill ref, run security checks, and preview changes before write.
Repo facts `naar scan --json` Inspect the structured repository facts that recommendation uses.
Installed state `naar list` See what Naar currently manages in this repository.
Lifecycle history `naar history` Inspect local install and uninstall activity across projects on this machine.
Target inspection `naar targets list` Review stable, experimental, deprecated, and research-only assistant targets.

Flags and safety controls

Automation and safety are both first-class. These are the flags that affect write behavior and trust decisions the most.

Flag Meaning
`--json` Emit structured JSON. Install flows still do not write unless `--apply` is present.
`--dry-run` Preview the install plan without writing files.
`--yes` Accept normal confirmation prompts in automation, but it does not bypass risky security review by itself.
`--non-interactive` Disable prompts. Risky installs still require explicit flags.
`--allow-risky` Required to proceed non-interactively when fetched-bundle review marks a selection risky.
`--target <id>` Constrain install or recommendation behavior to one or more assistant targets.
`--provider <id>` Limit discovery to one or more providers.
`--history false` Disable local lifecycle-history recording for the current run.
`--reinstall` Allow reinstalling a provider ref that is already installed.

Targets

Targets describe where Naar can write managed skills, rules, or instructions for different AI coding tools.

Stable defaults

Claude project skills, Cursor rules, GitHub Copilot repo instructions, and Codex repo skills are the conservative default set.

Beyond the defaults

Experimental, deprecated, AGENTS.md, and research-only targets are visible through the CLI but are opt-in or non-writeable where appropriate.

List targets

naar targets list

Inspect one target

naar targets inspect codex_repo_skills

Providers

Providers are the upstream catalogs that Naar queries for skills.

Current providers

Anthropic and ClawHub are supported today. Anthropic can fall back to GitHub-backed catalog discovery when API credentials are not set.

Provider filtering

Use --provider when you want to constrain search, recommendation, or guided flows to a smaller source set.

Local history

Naar records install and uninstall lifecycle data locally so you can inspect what it manages across repositories.

Summary

naar history

Project list

naar history list

Skill usage

naar history skills

Privacy boundary

Local history is local-only. It stores project paths, timestamps, broad stack facts, skill metadata, and lifecycle events. It must not store source code, secrets, or terminal history.

Troubleshooting

Most issues fall into a few buckets: environment, provider access, target mismatch, or intentional security blocking.

Quick checks

  • Check Node.js version first.
  • Run naar scan --json if recommendations seem wrong.
  • Run naar targets list if a target behaves differently than expected.
  • Use --dry-run when install results are surprising.

Need help?

If behavior looks wrong, open an issue with the exact command, terminal output, and whether you were using search, go, or direct install.

Report an issue