Hikae

日本語

Hikae is a local CLI for managing personal todos and notes. Its human-oriented commands and versioned machine interface for AI and automation operate on the same authoritative SQLite store. It requires no remote service or account.

Get started

Download the binary for your platform and SHA256SUMS from a Forgejo Release.

Platform	Binary
macOS (Apple Silicon)	hikae-darwin-arm64
macOS (Intel)	hikae-darwin-amd64
Linux (x86_64)	hikae-linux-amd64
Linux (ARM64)	hikae-linux-arm64

For example, on macOS (Apple Silicon), put the two downloaded files in the same directory and run:

grep -F '  hikae-darwin-arm64' SHA256SUMS > hikae-darwin-arm64.sha256 && \
  shasum -a 256 -c hikae-darwin-arm64.sha256 && \
  rm hikae-darwin-arm64.sha256 && \
  mv hikae-darwin-arm64 hikae && \
  chmod +x hikae && \
  ./hikae --help

On Linux, replace shasum -a 256 with sha256sum. After verification, place hikae in any directory on your PATH if desired.

To build from source, use Go 1.26 or later:

go build -o hikae ./cmd/hikae
./hikae --help
./hikae --version

First actions

# Add an Item.
./hikae add "Buy milk" --date 20260720 --tag home

# Show open Items. `hikae list` shows open, parked, and done Items.
./hikae

# Complete an Item using the ID prefix shown in the list.
./hikae done 1a2b3c4d

# Inspect it.
./hikae show 1a2b3c4d

Dates accept either YYYY-MM-DD or YYYYMMDD. Items can also have a description, tags, a time, and recurrence. Consult the running binary's manual for details:

./hikae --help
./hikae docs

Data and safe operation

The default data directory is ~/.local/share/hikae. Change or isolate it with HIKAE_DATA_DIR or the global --data-dir DIR option. New data directories are created with owner-only permissions; an existing directory writable by group or other users is rejected. Hikae is for local macOS/Linux filesystems; network filesystems and symlinked data directories or databases are out of scope.

Backup never replaces live data, and restore always writes to a new directory.

hikae backup --output hikae-backup.sqlite
hikae restore --from hikae-backup.sqlite --to-data-dir ./hikae-restored
hikae --data-dir ./hikae-restored list

delete removes an Item from the live store. Take a backup first.

AI and automation

AI and scripts must use the machine interface rather than parsing human-readable list or show output. Before operating, read the running binary's procedure and request schema.

hikae docs machine
hikae machine v2 schema request

Machine v2 provides JSON requests and responses, revision guards, request-ID idempotency, and JSON Lines batch processing. See Machine interface v2 (日本語) for the contract and staged procedure. Machine v1 has no migration period and its commands return a v2 usage error.

Capabilities and non-goals

• Add, list, show, update, edit multiline descriptions, park, unpark, complete, reopen, and delete Items.
• Dates, times, tags, literal search, and recurrence.
• SQLite backup and restore to a new directory.
• An embedded human manual and the machine v2 runtime schema.

Hikae is for one OS user and a local filesystem. It does not provide remote sync, multiple users or devices, a web/mobile UI, a resident daemon, or notifications.

Development and further documentation

make check
make e2e-parked-machine-v2
make e2e-backup-restore

See Operations and recovery (日本語) and Acceptance procedure (日本語) for isolated-directory verification. Implementation plans and acceptance criteria are retained in docs/*-plan.md.

License

MIT