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:.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
WebSearchandWebFetchtopermissions.denyin~/.claude/settings.json. It also removes them from the allow lists in the.claude/settings.local.jsonfiles it finds under your home directory, in folders such as~/dev,~/projectsand~/src. - In OpenCode, it sets
permission.websearchtodeny.
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.
Search
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:
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-dateform (YYYY-MM-DD). It covers that whole day in UTC. An--*-afterflag resolves to00:00:00on that date, and a--*-beforeflag resolves to23: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 as7dor30min). It resolves to the request time minus the delta, truncated to the minute, even if you set--query-time. The units aremin(minutes),h(hours),d(days),w(weeks),mo(30 days) andy(365 days).
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.
Point-in-time search
--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:
--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:
--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:
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:
--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.
--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:
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:
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
3before it sends a request. keenable monitors deletewithout--yesexits with1and 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 with0.
Credits left
With an API key, each response’susage.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: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, pointSSL_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.
cause and hint:
-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, setKEENABLE_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:
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://. Plainhttp://works only forlocalhost,127.0.0.1and::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 tohttps://gateway.example.com/keenable/v1/search. - The CLI removes trailing slashes.
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":
-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:
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.
Related pages
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.