Getting Started

Install rem — a CLI for macOS Reminders — and start managing your reminders from the terminal in under a minute. Covers install script, go install, shell completions, and AI agent skills.

Requirements

  • macOS 10.12+ (Sierra or later)
  • Go 1.21+ (for building from source)
  • Xcode Command Line Tools (provides clang and framework headers for cgo)

On first run, macOS will prompt you to grant Reminders access in System Settings > Privacy & Security > Reminders.

Installation

go install github.com/BRO3886/rem/cmd/rem@latest

This compiles the single binary with EventKit support via cgo — no separate helper binaries needed.

From source

git clone https://github.com/BRO3886/rem.git
cd rem
make build

The compiled binary will be at bin/rem. To install system-wide:

make install

Quick start

List your reminders

rem list

Create a reminder

rem add "Review pull request" --due tomorrow --priority high --list Work

Use natural language dates

rem add "Team standup" --due "next monday at 9am"
rem add "Submit report" --due "in 3 hours"
rem add "Friday wrap-up" --due "eod friday"

Complete a reminder

Use the short ID shown in the list output:

rem complete 6ECE

Short IDs are prefix-matched — you only need enough characters to be unique.

View your stats

rem stats

Search across all lists

rem search "pull request"

Output formats

Every command supports three output formats:

rem list -o table    # colored ASCII table (default)
rem list -o json     # machine-readable JSON
rem list -o plain    # simple text, one per line

The NO_COLOR environment variable is respected for colorless output.

Shell completions

Generate completions for your shell:

# Bash
rem completion bash > /usr/local/etc/bash_completion.d/rem

# Zsh
rem completion zsh > "${fpath[1]}/_rem"

# Fish
rem completion fish > ~/.config/fish/completions/rem.fish

AI Agent Skills

rem ships with an embedded skill that teaches AI coding agents (Claude Code, Codex CLI, OpenClaw, etc.) how to use it effectively. Install it with:

rem skills install

This copies the skill files to the agent’s skill directory (e.g. ~/.claude/skills/rem-cli/). The skill includes command references, date parsing docs, and usage examples.

rem skills status      # Check installation status
rem skills uninstall   # Remove the skill

You can also target specific agents:

rem skills install --agent claude    # Claude Code only
rem skills install --agent codex     # Codex CLI only
rem skills install --agent openclaw  # OpenClaw only
rem skills install --agent all       # All supported agents

What’s next

  • Commands — Full reference for all 20 commands
  • Architecture — How rem works under the hood
  • Go API — Use rem as a library in your Go programs
Next Commands