Your sources in the terminal
toopost is a command-line client for your Toopost inbox: an arrow-key menu, feed, full text, search, AI answers with citations, saved posts and sources, with JSON output and a local MCP server for scripts and coding agents.
toopost CLI
npm package toopost. Version 0.3.0, Node 18.18 or newer. Pro or Maxi. Every command has --json; errors go to stderr with stable codes and exit codes (3 NOT_LOGGED_IN, 4 PLAN_REQUIRED, 5 NOT_FOUND, 6 LIMIT, 7 NETWORK).
Menu and sign-in
npx toopost # arrow-key menu
toopost login # prints a link and a code, approve in the browser
toopost feed --since 24hAI agents
npx toopost skills --mcp # Claude Code, Cursor, AGENTS.md
claude mcp add toopost -- npx -y toopost mcpHeadless agents and CI
export TOOPOST_TOKEN=... # API token with All permissions
toopost feed --json --since 6h | jq '.items[] | .title'| toopost | Arrow-key menu: sign in, today's main stories, ask, feed, search, saved, sources, usage, install into your AI agent |
| toopost login | Prints a link and a code to approve in the browser. Works over SSH and inside coding agents. --browser for the loopback flow, --token for an API token |
| toopost feed | Posts from your sources, newest first. --since 24h, --source, --folder, --unread, --search, --limit |
| toopost read <id> | One post with its full text. --fetch downloads the page when the text is missing |
| toopost search <query> | Full-text search. Quotes, -exclude, site:host and dates like "last week" |
| toopost ask "<question>" | AI answer over your sources, streamed, with numbered citations |
| toopost saved · save <id> · unsave <id> | Saved posts |
| toopost sources · sources add <url> · sources remove <id> | Follow a site, feed, Telegram, YouTube or Reddit channel |
| toopost usage · whoami | Plan, usage percent and reset date |
| toopost skills --mcp | Set up Claude Code, Cursor and Codex in this folder |
| toopost mcp | Local MCP server on stdin/stdout for AI agents |
CLI FAQ
- What is the toopost CLI?
- An npm package (toopost, version 0.3.0) that reads your Toopost inbox from the terminal: an arrow-key menu with today's main stories, plus feed, full text, search, AI answers with citations, saved posts and sources. It needs Node 18.18 or newer.
- Is it made for AI agents?
- Yes. Every command has --json, errors go to stderr as one JSON line with a stable code (NOT_LOGGED_IN, PLAN_REQUIRED, LIMIT, …) and exit codes are stable (3 not signed in, 4 plan required, 5 not found, 6 limit, 7 network). toopost mcp runs a local MCP server with 14 tools, and toopost skills --mcp writes a Claude Code skill, a Cursor rule, an AGENTS.md section and the MCP config for the project.
- Which plan do I need?
- The CLI, MCP (local and hosted at mcp.toopost.us) and API tokens require Pro or Maxi. On Free you can sign in, and whoami and usage work; reading commands answer with an upgrade message and exit code 4.
- How does sign-in work?
- toopost login prints a link and a code; open the link, check the code and click Approve. Nothing secret is typed into the terminal, so it works over SSH and inside coding agents. toopost login --browser uses the older OAuth loopback flow, and toopost login --token saves an API token. The token is stored in ~/.config/toopost/credentials.json with mode 0600, lasts 90 days and renews while in use.
- How do I use it in CI or on a server without a browser?
- Create an API token with All permissions in Connections → API and set TOOPOST_TOKEN. It takes precedence over the saved login. On a remote shell, toopost login --no-browser only prints the link and the code.
- Can it talk to staging?
- Yes: --api-url staging is a shortcut for https://api-staging.toopost.us. The default API is https://go.toopost.us.