Documentation · apr 2026 · 4 min

Quick-start guide for an open-source CLI tool

by Dominica Luparello

Project brief

Provenance · Spec exercise

Audience: New contributors using a POSIX-compatible shell who are comfortable with files but may be new to command-line tools
Objective: Get a reader from prerequisites to a verified first result without sending them elsewhere
Role: Documentation writer: task analysis, information architecture, examples, and line edit
Constraints: POSIX-compatible shell; one primary path; commands must be copyable; expected output and recovery steps stay beside the action

Deliverables

Quick-start guide
Command examples
Troubleshooting notes

Approach

Define success as one local note being indexed, then reveal only the concepts and options required to reach and verify that state.

Spec exercise. Fieldnote, its package, commands, and output are fictional; there is no client relationship, usability study, or performance result to claim.

Fieldnote is a fictional command-line tool for indexing a folder of Markdown notes. This quick-start is written for a POSIX-compatible shell and uses illustrative commands that are part of the spec exercise; they do not install a real package. By the end, the fictional tool will have indexed one note and returned it in a search.

Before you start

Node.js 22 or later
npm available in your terminal
A POSIX-compatible shell such as zsh, bash, or dash
A folder where you can create two small files

1. Install Fieldnote

npm install --global @fieldnote/cli
fieldnote --version

The fictional version command should print a version number. If your shell says it cannot find fieldnote, close and reopen the terminal so it reloads the executable path. If the install reports a permissions error, use a Node version manager rather than rerunning the command with administrator privileges.

2. Create a notebook

mkdir fieldnote-demo
cd fieldnote-demo
printf '# Launch notes\n\nConfirm the release checklist.\n' > launch.md

The example creates a folder and one Markdown file. If you already have a notes folder, change into it and skip the file-creation command.

3. Initialize and index

fieldnote init
fieldnote index .

In this fictional interface, init creates a local configuration file and index scans Markdown files below the current folder. A successful first run reports that one file was indexed. Run both commands from fieldnote-demo; running them from its parent would widen the scan to unrelated files.

4. Verify the result

fieldnote search "release checklist"

The expected fictional result names launch.md and shows the matching sentence. No result usually means the file was created outside the indexed folder, the query differs from the note, or indexing did not finish. Check your current directory, open launch.md to confirm its text, and run fieldnote index . again.

Next steps

Add another Markdown file and rerun the index command.
Use fieldnote status to inspect the fictional index location and file count.
Keep the generated configuration with the notebook so collaborators use the same scope.