CLI reference

The Nessie CLI gives any terminal-based agent or script access to your Nessie library. It is installed as part of CLI access setup and available at nessie in your shell. Works with Claude Code, Codex, and any agent that can run shell commands.

The CLI talks to a local Nessie runtime. On macOS that can be the Nessie app over localhost; the cross-platform Rust CLI talks to Nera over authenticated loopback gRPC. The corresponding runtime must be running. Use nessie status to check the connection. Cloud-backed CLI paths for direct cloud search and faster shared-source access are planned.

Nessie as a filesystem

The CLI exposes your Nessie library as a filesystem and uses Unix coreutil verbs. Everything Nessie holds - an integration root, an Obsidian vault or folder, a synced transcript, a saved context, a profile section, a single chat message - is a node addressed by its UUID. There are no path strings; you navigate by UUID.

Nodes play two roles:

• Directories are container nodes (integration roots, vaults, folders). List them with ls.
• Files are readable nodes (contexts, notes, transcripts, messages). Read them with cat, head, or tail.

A node can be both at once - a meeting note is a readable summary that also contains its full transcript - so ls shows each node's raw kind rather than a single file-or-directory bit.

Connection and identity

• nessie status - Show app health: version, CLI access, signed-in user, last ingestion, and last cloud sync
• nessie whoami - Show the authenticated Nessie user: name, email, user ID, and teams

Check-in

• nessie check-in - Load generated profile sections plus recent Nessie activity for an agent session
• nessie check-in --recent-limit 10 - Control recent activity count (1 to 25, default 10)
• nessie check-in --hook - Emit host hook JSON for Claude Code or Codex session startup

Navigating: ls and stat

ls is the first-class browser. With no argument it lists the source roots: connected integrations, the Contexts and Chats roots, and readable shared source roots. A directly shared session may itself be a root, so use its returned kind instead of assuming every shared root is an integration. Shared context folders live inside the Contexts root and can contain mixed-owner children. Pass a node UUID to list its direct children, then drill in by listing a child's UUID. stat shows a node's metadata and its place in the tree without dumping its content.

• nessie ls - List the source roots
• nessie ls - List the direct children of a directory node
• nessie ls --type meeting - Filter children by group, such as transcript, context, or meeting
• nessie ls --type claude_code_chat - Filter by a raw node kind, as shown in each node's kind field
• nessie ls --since 2026-05-30 --until 2026-05-31 - Browse a time window
• nessie ls --owner me - List only the roots you own (the default already includes your own plus incoming direct and team shares)
• nessie ls --limit 100 --offset 0 - Page through children (default limit 100, max 500)
• nessie ls --json - Output raw JSON instead of the aligned table
• nessie stat - Print metadata only, for a file or a directory

The ls table prints kind owner updated id name, where owner is me or another person's email. A shared column is inserted after owner when the CLI can resolve an outgoing grant through the team directory; it shows a short headline of personal and team audiences (a team name, admins, a person, or +N when there are more). Whole-team and admin-only grants appear reliably. A personal grant outside a team, and sometimes a grant to one named teammate, may not appear, so a missing column does not prove every item is private; confirm the exact audience in the app's Share control. Incoming shares show their actual owner in the owner column instead.

There is no recursive ls yet. To search a whole subtree by content, scope a grep to the parent UUID.

Reading: cat, head, tail

These print a node's readable content as raw text, with no JSON wrapper. They work on contexts, Obsidian notes, meeting summaries, whole transcripts, and single chat messages, and they reject a pure directory with a message pointing you back to ls.

• nessie cat - Print the full content, with no length cap
• nessie head - Print the first 10 lines
• nessie head -n 40 - Print the first 40 lines (--lines also works)
• nessie tail - Print the last 10 lines
• nessie tail -n 40 - Print the last 40 lines

head and tail read only enough from that edge, so they are cheap on a long transcript where cat would be expensive.

Searching: grep

grep searches node content. It runs hybrid (semantic plus keyword) search by default. The optional second argument is a parent UUID that scopes the search to that node and all of its descendants, which is the right tool for "find this anywhere under this vault, root, or folder."

• nessie grep "database migration" - Search everything you can read
• nessie grep "launch bug" - Scope the search to one subtree
• nessie grep "pricing decisions" --type context - Filter by type or raw kind
• nessie grep "exact wording" -F - Fixed-string (literal) match instead of hybrid
• nessie grep "release blocker" --since 2026-05-30 --until 2026-05-31 - Restrict to a time window
• nessie grep "hiring criteria" --owner me - Narrow to just your own sources
• nessie grep "migration" --repo . - Restrict to the current git repo (coding-session content only)
• nessie grep "competitive analysis" --limit 20 - Return more results (default 10, max 500)

Results are grouped by document with the matching content and carry owner attribution. A single search is rarely enough: vary the wording, then cat the full node for each relevant hit before drawing a conclusion.

Teams and integrations

Use these to resolve teammate-shared work and named teammates before scoping an ls or grep.

• nessie team list - List teams, members, and resources shared with you
• nessie integration list - List personal and team-shared integration roots
• nessie integration list --platform claude_code - Filter roots by platform
• nessie integration list --status team_remote - Show only team-shared roots
• nessie integration list --team-id - Show roots for a specific team

Typical team flow: list team-shared roots with nessie integration list --status team_remote, find the teammate's root and owner ID, then search inside it with nessie grep "release blocker" --owner . Results include provenance so an agent can distinguish your local history from a teammate's shared source.

For collaborative contexts, open the virtual Contexts root with nessie ls, then list the teammate-owned folder inside it. A directly shared transcript may be read from its own root ID. The CLI applies repository/session exclusions and folder overrides before returning results, so the listed or readable target is authoritative.

Managing sharing

Use sharing get, sharing add, and sharing remove to manage direct grants for an integration account, an individual agent session, a Nessie context, or a Nessie folder. These commands have the same behavior through the Mac app and the cross-platform Rust CLI with Nera. The corresponding local runtime must be running and Cloud Sync must be enabled.

• nessie sharing get — return the node's direct grants, including audience, scope, exclusions, and context or folder access mode
• nessie sharing add --team --audience everyone — share the entire node with everyone in a team
• nessie sharing add --team --audience admins — share with team admins
• nessie sharing add --team --audience user --user — share with a named teammate; repeat --user for several teammates
• nessie sharing add --audience user --email person@example.com — share directly with an existing Nessie user outside a team
• nessie sharing add --team --scope repos --repo github.com/org/repo — share selected repositories from a coding-agent integration; repeat --repo for several
• nessie sharing add --team --scope folders --folder /absolute/workspace/path — share selected repo-less workspace folders; repeat --folder for several
• nessie sharing add --team --audience everyone — share one specific agent session instead of its whole integration
• nessie sharing add --team --audience everyone --access viewer — grant Viewer access to a context or folder; use --access editor to allow edits

The default scope is all. Repository scope requires at least one exact normalized --repo key and may also include --folder values for repo-less sessions. Folder scope accepts only --folder. Use --access viewer|editor only with Nessie contexts and folders. Re-running sharing add for the same audience changes that grant.

To remove grants:

• nessie sharing remove --team — remove every direct grant for the team, including grants to named team members
• nessie sharing remove --team --team-acl-only — remove only the team's Everyone or Admins grant and preserve named-member grants
• nessie sharing remove --team --user — remove selected team-member grants
• nessie sharing remove --user — remove a personal grant; use sharing get to resolve its user ID

These commands manage private Nessie access grants. They do not create or disable public browser links.

Owner scope

Discovery and search default to everything you can read - your own sources plus incoming direct and team shares. Narrow to just your own with --owner me (or --owner current_user). Use --owner direct_shared for incoming peer-to-peer grants, --owner team_shared for incoming team-derived grants, or --owner shared for both incoming paths; team remains a compatibility alias for team_shared. Pass a user ID or email (--owner tiger@nessielabs.com) only when you specifically want that person's readable sources. --owner is available on ls, grep, search, node list, node search, source list, and transcript list.

Writing: mkdir, tee, replace-lines, sed, mv, rm, rmdir, delete

These write to your context library. Folders organize contexts; contexts are your saved context documents. Transcripts and other synced sources are read-only, except that a whole synced conversation can be deleted with delete.

• nessie mkdir "" - Create a folder at the top level
• nessie mkdir "" --emoji "📁" - Create a nested folder with an emoji
• echo "" | nessie tee "