Private beta

The Filter CLI

Use the command line to manage your Filter workspace.

Read and update your workspace from a terminal, script, or agent.

npm install -g filter-cli

filter auth login
filter feed list --pretty
filter feed save --id 1234 --confirm

Overview

Installing the CLI gives you the filter command. Log in once, then use it to list feed items, save articles, manage sources, view reports, and search the web from your Filter account.

Run filter [command] --help for command help.
Add --pretty when you want human-readable output.
Add --confirm when a command changes account data.

Install

Install globally:

npm install -g filter-cli

Or run without installing:

npx filter-cli catalog

Auth

The recommended flow: generate a token from web settings, then paste it into the CLI.

filter auth login
# → prints the URL to generate a token
# → prompts for the token, validates it, saves it

filter auth whoami

Other ways to authenticate:

# Pass a token non-interactively (for scripts / CI)
filter auth login --token YOUR_TOKEN

# Email + password (power-user fallback)
filter auth login --email you@example.com --password ...

Profiles

Saved at $XDG_CONFIG_HOME/filter/config.json (or ~/.config/filter/config.json). Resolution order: CLI flags > FILTER_API_TOKEN / FILTER_API_BASE_URL env vars > saved profile.

Quick reference

filter catalog                         # List all commands as JSON
filter feed list --read unread         # Unread feed items
filter feed reader --id 1234           # Read an article (preview)
filter feed reader --id 1234 --full    # Read an article (full)
filter feed save --id 1234 --confirm   # Save to library
filter feed tags --id 1234 --tag AI --mode add --confirm
filter highlights list                 # Saved highlights
filter sources list                    # Connected sources
filter sources create --type rss --url https://example.com/feed.xml --confirm
filter views list                      # Custom views
filter reports list                    # Generated reports
filter ai web-search --query "latest AI research"
filter auth whoami                     # Active account

Run filter <command> --help for full options on any command.

Commands

The Filter CLI supports commands for feed items, sources, views, reports, highlights, auth, and AI helpers. Below are some of the most used ones.

filter auth login
filter auth login --token YOUR_TOKEN

`auth whoami`

Show the account attached to the active token.

filter auth whoami

`feed list`

List feed items from your workspace.

filter feed list
filter feed list --read unread
filter feed list --source rss --pretty

`feed reader`

Open the readable content for a feed item.

filter feed reader --id 1234
filter feed reader --id 1234 --full

`feed save`

Save a feed item to your library.

filter feed save --id 1234 --confirm

`feed tags`

Add, remove, or replace tags on a feed item.

filter feed tags --id 1234 --tag AI --mode add --confirm
filter feed tags --id 1234 --tag Research --mode set --confirm

`highlights list`

List saved highlights and snippets.

filter highlights list
filter highlights list --topic Research --q embeddings

`sources list`

List connected sources and their status.

filter sources list

`sources create`

Create a new source connector.

filter sources create --type rss --url https://example.com/feed.xml --confirm
filter sources create --type youtube --url https://youtube.com/@openai --confirm

`views list`

List saved views.

filter views list

`reports list`

List generated reports.

filter reports list
filter reports list --view-id 3

`ai web-search`

Run a cited web search for current information.

filter ai web-search --query "latest OpenAI API pricing"
filter ai web-search --query "Anthropic news" --allowed-domain anthropic.com

`catalog`

List all available commands as JSON.

filter catalog

Global flags

Flag	Purpose
--json	Emit JSON (default)
--pretty	Emit human-readable output
--base-url	Override the API base URL
--token	Override the bearer token for one call
--profile	Select a saved profile
--timeout	HTTP timeout in milliseconds
--confirm	Allow confirm-gated write commands to execute
--full	Request full content (not preview) where applicable
--help	Command-specific help

JSON contract

Every command returns the same shape:

{
  "ok": true,
  "status": "ok",
  "data": {},
  "error": null,
  "meta": {
    "command": "feed list",
    "safety": "auto"
  }
}

meta.pagination appears on paginated lists. meta.truncated appears on preview commands.

Exit codes

Code	Meaning
0	Success
2	Validation failure
3	Auth failure or missing token
4	Not found
5	Confirmation required
6	Transport, timeout, or server failure

Confirmation gating

Write commands marked confirm never prompt interactively:

filter sources delete --id 5
# → status: "pending_confirmation", exit code 5

filter sources delete --id 5 --confirm
# → executes

This makes the CLI safe to compose into scripts and agent workflows. An agent that forgets --confirm hits a structured no-op rather than a silent mutation.

Using with agents

Agents (Claude Code, Cursor, custom scripts) can call the CLI directly — no MCP server needed.

filter catalog returns every shipped command as JSON, including description, args, safety, and usage. Agents should call catalog first to discover commands, then shell out to specific calls and parse the standard { ok, status, data, error, meta } envelope.

filter catalog | jq '.data.commands[] | select(.safety == "confirm")'