Onyx Notes

Onyx Notes is a command-line note manager built around plain Markdown files. It is designed for a workflow where notes stay local, portable, scriptable, and easy to open in whatever editor I already use.

The tool keeps the core interaction intentionally small: create notes, list notes, edit notes, delete notes, manage templates, and switch between configured note contexts. It is not trying to replace a full note-taking application. It is an intentionally thin CLI that complements a Markdown-based notes workflow from the terminal.

Why I Built It

I have used Obsidian in the past, and I really enjoyed the habit it helped me build. The friction was not the idea of a Markdown vault; it was the interface. I spend most of my time in the terminal, so opening a separate application became enough friction that it changed how often I captured notes.

Onyx started as a couple of zsh aliases pointed directly at my Obsidian vault. That was enough to prove the workflow was useful, but it was not enough structure to feel like a real tool. I wanted Onyx to be an homage to Obsidian rather than a total replacement: keep the Markdown-first, vault-oriented workflow, but make the terminal the primary interface.

The goal was to make common note operations fast from the terminal while preserving the advantages of plain files:

• Notes are Markdown files on disk.
• Note metadata is stored as front matter.
• Editing happens through the user's configured editor.
• Different vaults can be represented as named contexts.
• Templates can standardize repeated note formats without forcing a specific writing workflow.

The API is intentionally thin. Notes can be daily notes, project notes, engineering notes, meeting notes, or something else entirely. I considered adding a dedicated daily subcommand that would effectively be an alias for creating or editing a note with a specific template, but that would have moved the tool toward prescribing a workflow. A shell alias can solve that locally without creating extra CLI surface area for everyone else.

What It Does

Onyx is written entirely in Go and exposes three primary areas of functionality.

Notes

The note commands manage Markdown files in the active vault:

onyx note new scratch
onyx note new daily-log --template daily
onyx note ls
onyx note edit scratch
onyx note delete scratch

New notes are created with front matter so metadata is available immediately:

---
name: "scratch"
created: 2026-06-01T17:27:46Z
tags: []
---

Templates

Templates provide reusable starting points for notes:

onyx template new daily
onyx template ls
onyx template edit daily
onyx template delete daily

A template can be selected explicitly when creating a note, or configured as the default template for a context. In the MVP, templates are file-based starters. A future version could add Go template support with a curated set of helpers, but keeping templating simple was the right tradeoff for the first version.

Contexts

Contexts let the same CLI point at different note vaults. This makes it possible to separate notes by workflow, project, environment, or machine-specific setup without changing command habits.

onyx config set-context work --vault ~/notes/work --default-template daily
onyx config use-context work
onyx config current-context
onyx config get-contexts
onyx config view

| Current | Name    | Vault                            | Default Template |
|---------|---------|----------------------------------|------------------|
| *       | default | /Users/jacobschwartz/.onyx/notes |                  |

The configuration model keeps the active context and the vault/template settings together:

{
  "current_context": "default",
  "contexts": {
    "default": {
      "vault": "~/.onyx/notes",
      "default_template": ""
    }
  }
}

Design Choices

The important design decision was restraint. Onyx does not try to replace an editor, database, sync engine, or publishing system. It stays focused on the few operations that make terminal-based note capture feel consistent.

That led to a few practical choices:

• Markdown remains the source of truth.
• Vaults are regular directories.
• Templates are regular Markdown files.
• Context switching is explicit and inspectable.
• Shell completions help the CLI feel native during day-to-day use.

The command structure was designed so subcommands can grow independently. Any one of the major command groups could become the root of its own tool if the project ever needed to split apart. That structure also supported a testable design, because command behavior can be reasoned about in smaller pieces instead of being concentrated in one large entry point.

Onyx also generates shell completion scripts, including completions for contexts, templates, and notes. That matters because a note CLI becomes much more useful when the shell can discover available notes and templates without extra memorization.

What I Learned

Onyx is a good example of a small tool where the complexity is not in a large feature set, but in making the interaction model feel predictable. The CLI has to handle configuration, filesystem conventions, editor handoff, note naming, templates, and context-specific behavior without making the user think about those mechanics every time they create a note.

The project reinforced a few engineering habits I care about:

• Favor workflows that preserve user ownership of data.
• Keep command surfaces narrow and composable.
• Make state visible through commands like config view and config get-contexts.
• Treat shell completion as part of the user experience, not an afterthought.
• Avoid features that can be better handled through composition.

The biggest takeaway is that building tools for your own workflow is rewarding. A project does not have to justify itself by serving every possible user. It can solve one real problem well, stay small, and still leave room for a community to shape the roadmap if it ever gets adoption.

Status

Onyx Notes is currently a personal CLI project. The foundation is in place for local Markdown note management, template-driven note creation, and multi-context vault workflows.

Future improvements could include richer metadata querying, better note discovery, validation around templates and vaults, import/export helpers for common Markdown-based note systems, and Go-template-powered note templates with a curated set of helpers.