Does the Postal CLI work without the desktop app?

It will write a capture to disk, but for now those captures only reach the signed-in web app after desktop Postal opens and drains the local inbox. Install the Mac app if you want Grok or Claude Code to update what you see at app.postal.wtf.

Which agents can use the Postal CLI?

Anything that can run a shell command: Grok, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Windsurf, Aider, scripts, and cron. Point them at ~/.local/bin/postal and a short instruction block.

How do I install the postal command?

It ships with the desktop app. Open a workspace and Postal writes ~/.local/bin/postal. Add that directory to your PATH if it is not already there.

Postal › CLI

A command your agents already know how to run

The postal CLI is how Grok, Claude Code, Cursor, Copilot, and anything else in a terminal put work on your board — instead of a session todo that vanishes when the chat ends.

Get the desktop app Agent snippets

Capture

postal "Meeting notes from standup"
postal --type task --due 2026-08-22 "Ship CLI docs"
postal --label Work "Follow up with design"
echo "idea from a pipe" | postal

Built for agents

You should not copy-paste from a coding agent into a todo app. The agent should write the task itself.

One binary

~/.local/bin/postal — no SDK, no extra auth for the agent, no plugin.

Plain instructions

A few lines in CLAUDE.md, Grok rules, or .cursorrules. Paste-ready on /agents.

Your board, not their scratchpad

Captures become Postal tasks and notes — still there tomorrow, on desktop and on the web.

Any shell

Grok, Claude Code, Cursor, Copilot, Gemini, scripts, cron. If it can exec, it can capture.

Desktop is required for now

Sync

The CLI does not talk to the cloud by itself yet. It writes a capture on disk, then opens Postal.app so desktop can drain that inbox into Supabase. After that, app.postal.wtf updates like any other device.

If the Mac app is not installed, the item sits in ~/Documents/Postal/.postal/inbox/ until you open desktop. That is the current contract — not a permanent one, but it is the honest one. Postal for Mac →

Instruct an agent in one block

Drop this into Grok user rules, CLAUDE.md, .cursorrules, or Copilot instructions.

Instruction

When I ask to remember something, add a task, or capture a note, run:
  ~/.local/bin/postal "the text"
Options: --label NAME, --type task|note|research, --due YYYY-MM-DD, --url URL
If postal is missing, say so — the Postal desktop app installs it.
Desktop Postal must be installed so captures sync to the web app.

Per-tool files (Claude, Cursor, Copilot, Gemini, shell) are on postal.wtf/agents. Longer walkthrough: Claude Code tasks.

Commands

postal --help

postal "Quick note"
postal --label Work --type task "Deploy v2"
postal --due 2026-08-22 "File taxes"
postal --url https://example.com "Read this"
postal --workspace Cooking "Try 00 flour pasta"

# Skip launching the app (capture still queued on disk)
POSTAL_NO_OPEN=1 postal "Don't steal focus"

Default type is a note. Use --type task when it is something to do. The CLI installs at ~/.local/bin/postal the first time desktop opens a workspace.

CLI FAQ

Why does it open the desktop app?

Signed-in Postal uses the cloud as source of truth. The CLI writes a local inbox file, then opens Postal so that file is imported. Without desktop, the web app never sees the capture. Direct CLI login is the next step; this is the working path today.

Can I capture without focusing the window?

Yes: POSTAL_NO_OPEN=1 postal "…". The file is still queued. Open Postal later (or leave it running) and drain happens on launch or focus.

Does this work if I only use the web app?

Not for agent capture. The web browser cannot read ~/Documents/Postal. Install desktop if you want agents writing into the same board you open on your phone.

Is the CLI free?

Yes. It ships with Postal. Bring your own API key and the whole product is free forever; managed AI is optional.