Getting started with Nectar

Install the Apiary, run your first scan, and search your codebase by meaning. Written for anyone; no database knowledge required.

Related:

• What is Nectar?
• Nectar FAQ
• Nectar command reference

#1. Install the Apiary

Nectar comes with the Apiary. One command installs the whole stack and brings the Nectar daemon up on 127.0.0.1:3854, supervised by Doctor.

macOS or Linux

curl -fsSL https://get.theapiary.sh | sh

Windows (PowerShell)

irm https://get.theapiary.sh/install.ps1 | iex

#2. Preview the cost of the first scan

The first read-through of your codebase is called brooding. Preview exactly what it will cost, locally, before spending anything:

nectar brood --dry-run

This makes no model calls and writes nothing. As a rough guide, about 200 files costs around thirty cents, 2,000 files around three dollars, and 10,000 files around fifteen dollars.

#3. Run the first scan

When you are happy with the estimate, run the real scan:

nectar brood

Nectar reads each file once, writes a short description and a few topic tags, and stores them. Small files are described together in batches to keep the cost low; large files are described one at a time. If the scan is interrupted, it resumes where it left off.

#4. Search by meaning

Now ask a question shaped like an idea, not a file name:

nectar search "where do we handle user authentication"

You get back the files that do the work, even ones not named anything like "auth." Add --limit to control how many results come back, or --json for a machine-readable list.

#5. Share it with your team

Commit the map Nectar writes:

git add .honeycomb/nectars.json
git commit -m "add nectar understanding"

Teammates who clone the repo inherit every description instantly, for free, with no re-scan. One person pays the one-time cost; everyone else inherits it.

#Day to day

After the first scan there is almost nothing to do. Nectar watches your source and re-describes a file only when it meaningfully changed, and only after you pause editing. Cosmetic reformatting is ignored. On a typical day that is a handful of files at most, often zero.

#What next

• Read the common questions in the Nectar FAQ.
• See every command in the Nectar command reference.
• Understand the machinery in Nectar architecture.