·
4 min read
Notes from your terminal
Notes from your terminal
If you've already got a terminal open — running a backup, watching a deploy, scrolling a Claude Code session — pushing the result into a searchable Fresh Jots note should be one line, not three clicks. This post walks the two ways to do that:
1. **`curl`** — works on every box that has internet, no install, no wrapper.
2. **The `freshjots` CLI** — a single Bash script (~5 KB, one file, `bash 3.2+` and `jq`), short enough for cron.
Both authenticate the same way (a bearer token), hit the same API (`/api/v1`), and return the same shapes.
With `curl` — write a note to root of Fresh Jots profile
With `curl` — write a note to root of Fresh Jots profile
The headline endpoint is `POST /api/v1/notes/by-filename/:filename/append`. It creates the note on first call and appends on every call after (manual edits on the freshjots.com website are disabled) — so a single recipe covers both "make a new note" and "add to an existing one."
curl -X POST "https://freshjots.com/api/v1/notes/by-filename/cron-log/append" \
-H "Authorization: Bearer $FRESHJOTS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"text":"backup ok"}'That lands a note named `cron-log` at the root of your account. Run it again tomorrow and tomorrow's line gets appended below today's, in the same note, full-text searchable in the web UI.
If you want strict create-only semantics (error if the filename is taken, but don't simultaneously manually edit it on the freshjots.com site!), use `POST /api/v1/notes` instead:
curl -X POST "https://freshjots.com/api/v1/notes" \
-H "Authorization: Bearer $FRESHJOTS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"note":{"title":"deploy-2026-05-08","plain_body":"v1.4.2 green","format":"plain"}}'
With `curl` — write a note **into a folder**
With `curl` — write a note **into a folder**
Folders live in their own resource. You can't pass a folder *name* on note creation; you pass `folder_id`. So the recipe is:
**Step A — get a `folder_id`** (once; cache it for later runs):
# Either create a new folder...
curl -X POST "https://freshjots.com/api/v1/folders" \
-H "Authorization: Bearer $FRESHJOTS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"folder":{"name":"deploys"}}'
# ...or list the ones you already have to find the id.
curl "https://freshjots.com/api/v1/folders" \
-H "Authorization: Bearer $FRESHJOTS_TOKEN"The response carries `{"folder":{"id":42, ...}}`. Save that `42`.
**Step B — create the note with `folder_id`**:
**Step B — create the note with `folder_id`**:
curl -X POST "https://freshjots.com/api/v1/notes" \
-H "Authorization: Bearer $FRESHJOTS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"note":{"title":"2026-05-08","plain_body":"v1.4.2 green","folder_id":42}}'The note lands inside the `deploys` folder in one round-trip. From this point on, the by-filename endpoint finds it whether it's in a folder or not — so subsequent appends don't need to know about the folder at all:
curl -X POST "https://freshjots.com/api/v1/notes/by-filename/2026-05-08/append" \
-H "Authorization: Bearer $FRESHJOTS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"text":"smoke tests passed"}'> **Windows note.** PowerShell aliases `curl` to `Invoke-WebRequest`,
> which has different flags. Use `curl.exe` (ships with Windows 10+),
> or run the recipes inside WSL / Git Bash where they work unchanged.
With the `freshjots` CLI — write a note to root
With the `freshjots` CLI — write a note to root
Same outcome as the curl recipe above, with the auth header and JSON envelope folded into the command.
freshjots append cron-log "backup ok"
That's the whole call. Or pipe stdin in:
./backup.sh 2>&1 | freshjots append cron-log
Or, if you want to fail when the filename's taken instead of appending:
freshjots create scratch "first line of a brand new note"
The CLI works the same on macOS, Linux, BSD, and WSL. There's no native Windows binary — the API is plain JSON over HTTP, so on raw PowerShell you stay on the curl recipes.
With the `freshjots` CLI — write a note **into a folder**
With the `freshjots` CLI — write a note **into a folder**
New notes always land at the root. The clean workaround is one-time-only and leaves you with a CLI-only flow afterwards:
**Step A** — once, create the folder and seed the note via curl (recipes above). The seeded note now lives inside the folder.
**Step B** — every call after that, use the CLI normally. The `freshjots append <filename>` command resolves notes by filename regardless of which folder they live in, so the existing-in-a-folder note continues receiving appends from the short, cron-friendly form:
freshjots append 2026-05-08 "smoke tests passed"
If your workflow has many folder-bound notes you create on the fly, stay on `curl` for the create step. If you have a few long-lived buckets (`deploys/`, `cron-jobs/`, `claude-sessions/`), seed once and let the CLI run.
