Skip to main content
With keenable-cli, you search the web, fetch pages, run monitors and add Keenable to your AI clients, all from the terminal. The CLI ships as a single binary. Search and fetch work without an account. Monitors needs an API key. To use your key, run keenable login once. The CLI saves it and reuses it for every command. See Rate limits for the limits with and without a key.

Installation

Install the CLI with one of these methods:
The macOS and Linux installer downloads a .tar.xz archive, so the machine needs xz (the xz-utils package on Debian and Ubuntu, xz on Fedora and Alpine). On a minimal image or container where xz is missing, the installer fails while it unpacks the archive. Install xz and run it again, or use Homebrew or cargo install instead. Run keenable --version to check the install. It prints the installed version.

Quick start

These commands sign you in, add Keenable to your AI clients and run a search:
configure-mcp --all shows what it will change and asks you to confirm. The search prints ranked results with titles, URLs and excerpts.

Authentication

keenable login signs you in with a device code. The CLI prints a code and a link, and tries to open the link in your browser. On a remote machine, open the link in any browser and enter the code. After you approve, the CLI saves an API key to ~/.keenable/config.json. On a server or in CI, save an API key instead:
keenable login --api-key checks the key with the API before it saves the key. If the API rejects the key, the CLI doesn’t save it and exits with code 1. Prefer --api-key -, which reads the key from stdin. A key passed as an argument shows up in your shell history and in the process list that other users on the machine can see. The CLI keeps the key in ~/.keenable/config.json, readable only by you. keenable configure-mcp also writes the key into each client’s MCP config. keenable logout removes the saved key and lists the clients that still hold one. To remove it from them too, run keenable reset --all. To use a key without saving it, set KEENABLE_API_KEY or pass --api-key to keenable search or keenable fetch. The flag overrides the variable, and both override the saved key.

MCP setup

These commands show which AI clients have Keenable configured, add it to them or remove it:
configure-mcp and reset take the same client flags. --all selects every client the CLI detects on the machine: configure-mcp adds a keenable entry that points at https://api.keenable.ai/mcp. If you’re logged in, the entry carries your API key in the X-API-Key header. If you aren’t, the entry has no key and the client runs on the public tier. A keyless Codex or Devin Desktop entry points at the keyless endpoint, https://api.keenable.ai/mcp-public, instead, because /mcp publishes OAuth discovery, which can make Codex start a browser sign-in. To add your key later, run keenable login, then configure-mcp again. configure-mcp also turns off the client’s own web search, so the agent uses Keenable:
  • In Claude Code, it adds WebSearch and WebFetch to permissions.deny in ~/.claude/settings.json. It also removes them from the allow lists in the .claude/settings.local.json files it finds under your home directory, in folders such as ~/dev, ~/projects and ~/src.
  • In OpenCode, it sets permission.websearch to deny.
keenable reset removes the keenable entry and turns those tools back on. For Codex and Cursor, and for a routing rule, see Make Keenable the default web tool. For an agent with no MCP client, install the agent skill instead. Both commands ask you to confirm before they write. If stdin isn’t a terminal, they exit with code 1 and ask for --yes (-y), which skips the prompt. keenable search prints YAML for agents by default. These examples show each flag:

Exclude domains

--exclude-domain leaves hosts out of the results. Repeat the flag or separate hosts with commas. These two commands send the same list:
Each host also excludes its subdomains. The CLI trims spaces around each entry and sends a blank entry, such as the end of a.com,, as "", which the API rejects. When a script builds the flag from a variable that can be empty, leave the flag out instead. A rejected entry prints the invalid_filter error with the entry and the reason, and the command exits with code 8. The rules and limits are on Exclude domains.

Search mode

--mode takes pro or realtime. If you leave it out, the API uses your organization’s default mode, or pro if the organization has none. To set the mode for every search, save it with keenable config:
keenable config get prints the value. If the setting has no value, it prints nothing and exits with code 1. The CLI keeps these settings in ~/.keenable/config.json.

Date and time filters

--acquired-after, --acquired-before, --published-after and --published-before each accept one of these formats:
  • A date in RFC 3339 full-date form (YYYY-MM-DD). It covers that whole day in UTC. An --*-after flag resolves to 00:00:00 on that date, and a --*-before flag resolves to 23:59:59.999, so pages from the named day are kept at either end. To cut at an exact instant, pass a timestamp instead.
  • A timestamp in ISO 8601 form (YYYY-MM-DDTHH:MM:SS[.sss][±HH:MM]). If you leave out the timezone offset, the timestamp is read as UTC.
  • A relative delta (<number><unit>, such as 7d or 30min). It resolves to the request time minus the delta, truncated to the minute, even if you set --query-time. The units are min (minutes), h (hours), d (days), w (weeks), mo (30 days) and y (365 days).
These commands show what each format resolves to:
You can mix relative and absolute values in the two bounds of a window:
Deltas are truncated to the minute. At request time 2026-05-18T14:23:45Z, --acquired-after 2h resolves to 2026-05-18T12:23:00Z. A page acquired at 12:22:59Z is dropped, and a page acquired at 12:23:00Z is kept. --query-time runs the search against the index as it stood at one instant. Pages acquired after that instant are left out, so you get the results the index would have returned then. The flag takes the same formats as the filters above. This command searches the index as it stood on 30 May 2025:
Relative deltas still count back from the time you run the command, not from --query-time. To bound results around a past instant, use dates. This command returns pages published in the 30 days before 13 June 2026, as the index stood then:
A date-only --query-time resolves to 00:00:00 UTC, the start of the day. A date-only --*-before flag resolves to the end of the day. So --query-time 2026-06-13 cuts at the start of 13 June, and --acquired-before 2026-06-13 keeps all of 13 June.

Fetch

keenable fetch prints a page’s content as YAML by default:
In the output, published_at and acquired_at are RFC 3339 timestamps in UTC, such as 2026-11-03T19:34:43Z. Search results use the same format.

Truncated content

If the page is longer than --max-chars, the API cuts the content. The YAML output has total_chars, the length of the full page content, and truncated, which is true when the content was cut. This command caps the content at 100 characters:
The output flags the cut content:
To get the rest of the page, run the command again with a larger --max-chars. With -p, the CLI prints that hint below the content. If the content isn’t cut, the output has truncated: false.

Monitors

keenable monitors creates monitors and reads their results. A monitor is a standing query: each newly crawled page that is news about its topic becomes one of its results. Monitors needs an API key, so run keenable login first. Without a key, the command stops with exit code 3.
If you pass --webhook, create prints webhook.secret (whsec_...) once. Store it: you need it to verify webhook signatures. --idempotency-key <KEY> makes a retry safe: the same key with the same flags returns the monitor the first call created. delete asks before it deletes, and without a terminal it needs --yes. The other subcommands are get, run (one run and its results), deliveries (webhook attempts of the last 7 days) and stats. Bulk actions have no subcommand: use the API or an SDK. Run keenable monitors <subcommand> --help for each one’s flags. Output, errors and exit codes work as they do for search and fetch.

Session IDs

--session-id <ID> tags a search or fetch with your own ID. Pass the same ID on every call in one agent run to group those calls. The CLI sends the ID as the API’s session_id parameter. The API keeps the first 128 characters of the ID. These commands group a search and a fetch under one session:
Each command prints its usual output. The session ID doesn’t appear in it.

Errors

If a command fails, it exits with a nonzero code. In YAML mode, keenable search, keenable fetch and keenable monitors print the error to stdout as YAML, so your agent can parse it like a result. They also print a one-line summary to stderr. This command asks for an out-of-range number of results:
The API rejects the request, and the CLI prints the error:
The error can have these keys. Each key appears only when it has a value: Branch on type and code when they’re present, not on the text of error or message. With -p, the CLI prints the error and the hint to stderr. It adds a Docs: line with the docs_url and a Request ID: line when the API sent them.

Exit codes

keenable search, keenable fetch and keenable monitors exit with a code for each kind of failure, so a script can branch without reading the output. Search and fetch do so from CLI 0.5.1. Earlier versions exit with 1 for every failure. See Updating. The codes: When the API sends an error type, it sets the code: for example, every rate_limit_error exits with 4. Other commands exit with 1 on any error. keenable monitors has two cases of its own:
  • Without an API key, it exits with 3 before it sends a request.
  • keenable monitors delete without --yes exits with 1 and deletes nothing when it can’t ask you to confirm, for example when stdin isn’t a terminal. If you answer no at the prompt, it exits with 0.

Credits left

With an API key, each response’s usage.credits_remaining is what your organization has left after the call, in credits of $0.004 each. YAML output includes it, and -p prints it as Credits left: N (https://keenable.ai/console). See Balance and usage.

Updating

The CLI checks for updates once per hour. To update a Homebrew install, run:
If you installed with an installer script, run keenable update instead.

Proxies and corporate networks

The CLI trusts its bundled root certificates and your operating system’s certificate store, so a company root CA installed on the machine works without setup. If your network inspects TLS and the CA isn’t in the system store, point SSL_CERT_FILE at a PEM bundle that contains it:
SSL_CERT_DIR works too. When either is set, the CLI uses it instead of the system store and keeps its bundled roots. If the file is missing or isn’t valid PEM, every command stops with Invalid SSL_CERT_FILE: <path>: <reason>. To send requests through a proxy, set HTTPS_PROXY or ALL_PROXY. Put a proxy login in the URL. Hosts in NO_PROXY are reached directly, and lowercase names work too. Without these variables, the CLI uses the macOS or Windows system proxy settings. PAC files aren’t supported.
Changes to these variables take effect on the next command. When a request fails on the network, the error says why and suggests a fix. In YAML output, it adds cause and hint:
Add -v (--verbose) to any command to see the proxy in use, the certificate sources the CLI loaded and the full error chain:

API base URL

To send the CLI’s API calls to another address, such as a local gateway, set KEENABLE_API_URL to its base URL. Without it, the CLI calls https://api.keenable.ai. This command sends a search to a gateway on port 8080:
The CLI sends the search to http://127.0.0.1:8080/v1/search, or to /v1/search/public if no API key is set. The value must follow these rules:
  • It starts with https://. Plain http:// works only for localhost, 127.0.0.1 and ::1.
  • It has no query string and no fragment.
  • It has no user name or password.
  • The CLI keeps a path prefix. With https://gateway.example.com/keenable, searches go to https://gateway.example.com/keenable/v1/search.
  • The CLI removes trailing slashes.
Search, fetch, login and the API key check in configure-mcp all use this URL. configure-mcp still writes the production MCP URL, https://api.keenable.ai/mcp, into your clients. The SDKs read the same variable. If the value breaks a rule, the command exits with code 1 before it sends a request. This is the YAML output for KEENABLE_API_URL=http://example.com keenable search "rust async":
With -p, and for login and configure-mcp, the CLI prints the same message and hint to stderr.

Saved keys and other base URLs

The CLI sends a saved API key only to the base URL it was saved for. keenable login saves the key with the current KEENABLE_API_URL, or with https://api.keenable.ai when the variable isn’t set. A search or fetch against any other base URL stops with exit code 1 and sends nothing, so a KEENABLE_API_URL set by a project’s environment can’t send your key to another host:
To use a gateway, pass its key with KEENABLE_API_KEY or --api-key, or run keenable login with KEENABLE_API_URL set. The CLI follows a redirect only to the same scheme, host and port. A redirect to another host, or from https to http, fails with exit code 7, and the API key isn’t sent.

Connect your agent (MCP)

Connect the Keenable MCP server to Claude Code, Cursor, Codex and other clients for web search and fetch with no key. Sign in for higher limits and Monitors.

Claude

Add Keenable to Claude and Claude Code, and keep Claude’s own web search from competing with it.

Quickstart

Give your agent web search in under two minutes, with no account or API key. Paste one prompt into your coding agent, or install the SDK and search.

Keyless access

How to call search and fetch with no API key: the /public paths, the X-Keenable-Title header, /mcp-public, and the 1,000 per hour keyless limit per IP.