We’ve released the Buffy CLI: a single binary that lets you talk to your personal behavior agent from the terminal and from scripts.
If you already use Buffy in ChatGPT, Telegram, or Slack, the CLI gives you the same behavior core from the command line—no browser, no extra app. Create habits, send reminders, and manage settings and API keys without leaving your shell.
This post covers what the CLI is, how to install it, and how to use it day to day (and in automation).
What is the Buffy CLI?
The Buffy CLI is the official command-line interface for the Buffy API. It uses the same POST /v1/message and user/API-key endpoints that power the web app and channel integrations, so everything you do with the CLI updates the same Activity model (habits, tasks, routines) and reminder engine.
- What you get: Send natural-language messages to Buffy, get and set user settings (e.g. timezone, name), and list, create, or revoke API keys—all from the terminal.
- Who it’s for: Power users who live in the shell, developers wiring Buffy into scripts or cron jobs, and anyone who wants to add a habit or reminder without opening another tab.
You don’t get a second “CLI agent”; you get another interface to the same behavior agent you use in chat.
Install the CLI
- Download the latest binary from GitHub Releases (tags
v*, e.g. v1.0.2). Pick the build for your OS and architecture, for example:- Linux (x64):
buffy-1.0.2-linux-amd64 - macOS (Apple Silicon):
buffy-1.0.2-darwin-arm64 - Windows (x64):
buffy-1.0.2-windows-amd64.exe
- Linux (x64):
- Rename the file to
buffy(orbuffy.exeon Windows). - Put it in a directory that is in your PATH (e.g.
/usr/local/bin,~/bin, or your Windows PATH).
You can also build from source with Go 1.21+ (see the buffy-cli repo).
Get an API key
The CLI needs a Buffy API key (Bearer token). Use the same key you use for the API elsewhere.
- Sign up at buffyai.org if you haven’t already.
- Go to Account → API keys and create a key, or create one from the CLI if you already have a key:
export BUFFY_API_KEY=your_existing_key
buffy api-key create --label my-cli
Then set BUFFY_API_KEY in your environment, or pass --api-key KEY on each command.
Commands at a glance
| Command | Description |
|--------|-------------|
| buffy version | Show CLI version |
| buffy message --text "..." | Send a message to the behavior core (e.g. create a habit or reminder). With a user API key, the message is attributed to that user; use --user-id with system keys to act on behalf of a user. |
| buffy user-settings get --user-id ID | Get user settings (JSON) |
| buffy user-settings set --user-id ID [--name ...] [--timezone ...] | Update user settings |
| buffy api-key list --user-id ID | List API keys (IDs, labels) |
| buffy api-key create [--label ...] [--type user\|system] | Create a new API key (user = API key owner; use --user-id with system keys to create for another user) |
| buffy api-key revoke --id KEY_ID | Revoke a key by ID (from the list) |
Global flags: --api-base URL (e.g. for self‑hosted), --api-key KEY, --as-user USER_ID (for system keys acting on behalf of a user).
Example: add a habit from the terminal
With your API key set:
export BUFFY_API_KEY=your_key
buffy message --text "remind me to drink water every day"
Buffy’s behavior core will interpret the message, create the habit (or task/reminder), and reply. The same habit then shows up in your other channels—ChatGPT, Telegram, Slack—and in your daily briefing, because there is one behavior core behind all of them.
Use the CLI in scripts and automation
Because the CLI is just a binary that calls the API, you can:
- Cron or scheduled jobs: e.g. “every morning at 7, send a message to Buffy to log my morning routine.”
- Shell aliases: e.g.
alias buffy-remind='buffy message --text'for quick one-liners. - CI or internal tools: use system API keys to manage users or settings programmatically.
The same Buffy API and the same limits (e.g. plan limits for habits, tasks, routines) apply; the CLI is another client, not a separate product.
How this fits the rest of Buffy
Buffy is a personal behavior agent with one behavior core and many interfaces: ChatGPT, Telegram, Slack, the web app, and now the CLI. The CLI doesn’t replace those—it adds a terminal-shaped interface so you can stay in your workflow and still create habits, get reminders, and keep your settings in sync.
For a high-level picture of the API and how to plug in your own app, see:
Next step
- Next step: Install the CLI and send your first message: download from GitHub Releases, set
BUFFY_API_KEY, and runbuffy message --text "remind me to …". If you’re new to Buffy, start with How to Get Started With Buffy Agent in 5 Minutes.