Ezo CLI
Ezo CLI
ezo reads and changes your lists, items and notes from a terminal, for scripts, agents and anyone who would rather type. It works through the
Ezo API
, on every plan, and every write keeps the account's plan and access limits.
Sign in
Install the Ezo CLI package, which needs Node 22.12 or later, then connect it to your account:
ezo auth sign-in \
--server https://ezo.gs/api/v1 \
--app-url https://ezo.gsEzo opens a connection request in your browser. Sign in, compare the code with the one in your terminal, and choose Connect; --no-open prints the link instead of opening it. The connection lasts 90 days and shows in Settings under API access. ezo auth status shows the account and what the connection may do, and ezo auth sign-out revokes it and removes the saved token.
A token you already have can be given through EZO_TOKEN, or saved from standard input with ezo auth token --server https://ezo.gs/api/v1 --input -. Tokens are never accepted as command-line arguments. The saved configuration is a private file (mode 0600); --config, EZO_CONFIG and XDG_CONFIG_HOME choose where it lives.
First steps
ezo lists list --all
ezo items create 12abcd --title 'Bring water'
ezo notes set Ab12Cd --file ./notes.md
ezo notes get Ab12Cd > ./saved-note.md
ezo items complete Ab12CdLists and items are named by their Ezo IDs, which ezo lists list and ezo items list LIST_ID show. Positions count columns and rows from zero.
ezo --help lists every command, and ezo items create --help (or any other) shows one command with the options it takes; ezo items --help shows a group. A command takes only its own options: any other is refused before anything is sent, with the nearest it does take (Unknown option --titel for ezo items create. Did you mean --title?), and an option that needs a value never takes the next option as one. Each option is given once.
For completion of commands, options and their choices in your shell, add eval "$(ezo completion zsh)" to ~/.zshrc, or eval "$(ezo completion bash)" to ~/.bashrc.
In scripts
--json writes results to standard output and errors to standard error, both as JSON; connection instructions go to standard error too. Create and update commands take a JSON object with --input PATH or --input -, and note commands take --content, --file or text through --input. Piped note output is the note exactly as stored.
--dry-run prints the method, path and body of a write without a token or a request; access and plan are checked when the write is really sent. After an uncertain result, retry with --key and the same input for up to 24 hours: Ezo returns the first result rather than writing twice. A key used with other input is a conflict.
- 0
- Success
- 1
- A network or server failure
- 2
- Invalid input
- 3
- Access denied
- 4
- Not found or not available
- 5
- A conflicting write
- 130
- Interrupted
Notes, links and pictures
ezo mentions list NOTE_ID --all reads what a note mentions, and ezo mentions add NOTE_ID --list LIST_ID or --item ITEM_ID adds a mention at its end; retried with the same --key, it is added once. A link item keeps its address as its title: ezo urls get, open and refresh print it, open it, or fetch its title and icon again.
ezo images add LIST_ID --file ./photo.jpg --column 0 --row 0 adds a picture. A file up to 20 MB is turned upright, made at most 2048 pixels, stripped of its metadata and made a WebP on your computer before it is sent, and must then fit in 2 MB. images replace ITEM_ID --file PATH keeps the item's name, note and place, and images remove ITEM_ID takes only the picture away.
.ezo files
ezo lists export LIST_ID prints a list as a .ezo file: CSV whose cells are Markdown, with each item's note and board under it. --file PATH saves it instead, and never over an existing file. ezo lists import LIST_ID --file PATH puts a .ezo file on the list, below what it holds.
Calendar, folders and views
ezo calendar lists this month's dated items a line a day, --month 2026-10 another month and --all every date. ezo folders create --list LIST_ID+LIST_ID makes a folder on Home and lets Ezo name it, or --name NAME names it yourself. ezo compare get LIST_ID+LIST_ID reads two or three lists side by side, and ezo views save keeps them as a view.
Sharing and templates
ezo sharing token makes an invitation token without a request; keep it, and pass it through standard input to ezo sharing invite LIST_ID --recipient EZO_ID --role viewer --days 7 --input -. The answer holds the invitation's link. ezo templates list shows the published templates, templates source LIST_ID previews what a list of yours would publish, and templates publish publishes exactly that preview.