devnotes-cli

Command-line client for devnotes, a small shared notes app for teams and their agents. Capture a gotcha from the terminal:

echo "TIL: docker build cache misses on COPY . ." | devnotes add -t "Docker layer cache"
#kx7mp

It's built to be driven by coding agents as well as humans: there are no interactive prompts anywhere, --json gives you the raw API response untouched, hints go to stderr so stdout stays pipeable, and failures exit non-zero.

Prerequisites

• A running devnotes instance and an API token (created on the app's /settings/api-tokens page)
• Go 1.26+ if you are building from source

Installing

Grab a binary for your platform from the releases page, or build from source:

git clone https://github.com/ohnotnow/devnotes-cli.git
cd devnotes-cli
make install          # installs `devnotes` into /usr/local/bin
make install PREFIX=~/.local   # or somewhere that doesn't need sudo

go install github.com/ohnotnow/devnotes-cli@latest also works, but note the binary lands as devnotes-cli rather than devnotes.

Configuration

The client needs an API URL and token. Each can come from a flag, an environment variable, or a config file, in that order of precedence:

Flag	Environment	~/.config/devnotes/config
--url	DEVNOTES_URL	url=https://notes.example
--token	DEVNOTES_TOKEN	token=your-api-token

The config file is plain key=value lines; # comments and blank lines are ignored.

Usage

# capture a note - piped stdin, -b, or $EDITOR if you're on a terminal
echo "the fix" | devnotes add -t "A hard-won gotcha"
devnotes add -t "A hard-won gotcha" -b "the fix"
devnotes add -t "A hard-won gotcha"

# find notes (the list and searches are scoped to your channels)
devnotes search docker
devnotes search --broader docker   # widen across all channels
devnotes search --page 2 docker

# read one (notes are identified by short codes, shown with or without the #)
devnotes show kx7mp

# channels
devnotes channels                  # list channel ids and names
devnotes add -t "title" -b "body" --channels 2,5   # file under specific channels

# back up the whole pot, including soft-deleted notes (admin token required)
devnotes export > backup.json

Notes are attached to your default channels unless you pass --channels. A bare devnotes search lists your channels' notes newest first; --broader widens both the list and searches to every channel. When a scoped search or list finds nothing, a hint to retry with --broader is printed on stderr.

show prints a note as raw markdown. Add --json to any command to get the raw API response instead of the human-readable output.

Running tests

make test

The tests run against local httptest servers, so no devnotes instance or network access is needed.

Contributing

Clone the repo, make build, and run make test before and after your change. Fixes and small improvements are welcome; for anything bigger it's worth opening an issue first.

Licence

MIT