String CLI
Fetch pages as Markdown, search the web, crawl sites and run site integrations from a terminal or a coding agent with the string command.
The String CLI, string, calls the Web Access API from a terminal and prints each response to stdout, so you can pipe
it into other commands. Use it in shell scripts and in coding agents that run commands. From an MCP client, use the
hosted MCP server instead, and from your own code, the REST API.
string fetch and string search work without a key, so once it's installed you can run the first command
before you have an account:
string https://example.comIt prints the page as Markdown, trimmed here:
# Example Domain
This domain is for use in documentation examples without needing permission. ...Install
Every channel installs the same native binary, string. Install it through one channel only, since each one puts a
string command on your PATH.
# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/usestring/cli/main/install.sh | sh
# Homebrew
brew tap usestring/cli https://github.com/usestring/cli
brew install usestring/cli/string-
install.shdownloads the binary for your system from the latest GitHub release, checks it against the release'schecksums.txt, and puts it in~/.local/bin. SetSTRING_INSTALL_DIRto install somewhere else, orSTRING_VERSIONto a tag such asv0.2.0to install that release. It then runsstring init; passinitoptions aftersh -s --, orsh -s -- --no-initto skip it. -
Homebrew builds the binary from the release's source archive. Upgrade with
brew update && brew upgrade usestring/cli/string. -
Each GitHub release has archives for macOS, Linux and Windows on x86-64 and ARM64, and
.deb,.rpmand.apkpackages. On Windows, unzipstring_windows_amd64.ziporstring_windows_arm64.zipand putstring.exein a folder on yourPATH. -
The Docker image,
ghcr.io/usestring/cli, runs one command per container. Pass-e STRING_API_KEYto use your key:docker run --rm ghcr.io/usestring/cli search "web scraping with python" docker run --rm -e STRING_API_KEY ghcr.io/usestring/cli sitemap list
string --version prints the installed version.
Sign in
Start without a key. Add one when you need more than the keyless allowance, or a field or command that needs a key.
Without a key
With no key set, string fetch and string search run within the daily
allowance without a key. They send only the fields that page lists,
and the CLI refuses any other flag before it sends anything. After each call, stderr shows what is left of today's
allowance:
X-Keyless-Requests-Remaining: 48
X-Keyless-Credits-Remaining: 98
Ran without a key. For more, run `string login` or set STRING_API_KEY.string request, string sitemap, string integrations run and string balance need a key.
With an API key
A key lifts the keyless limits and the keyless field list, and runs every command. Requests with a key spend your organization's balance. Create one on the API keys page, as Getting a key describes, and give it to the CLI in either of two ways.
Pipe it to string login --with-token. The CLI checks the key with a request that costs nothing, then saves it.
Reading it from stdin keeps the key out of your shell history:
string login --with-token < key.txtOr set STRING_API_KEY. A key in the environment wins over a saved one, and the CLI never writes it to a file:
export STRING_API_KEY="YOUR_API_KEY"string login saves keys in ~/.config/string/credentials.json, or under $XDG_CONFIG_HOME/string/ when that is
set, readable only by your user. string whoami says which key commands use. string logout deletes the saved key; the
key itself works until you revoke it on the API keys page.
Through your browser
string login opens a String page in your browser and prints its link and a code. Sign in to String, check that the
page shows the same code, and approve. The CLI then saves a new API key, named "String CLI", for your organization. If
you don't have an account yet, sign up first. Each sign-in creates another key,
which counts toward your organization's key limit, and the earlier
ones keep working until you revoke them on the API keys page.
When nobody can wait at the terminal, as under a coding agent, string login --json prints the link and code as JSON
and exits. Give both to the person who will approve, then run string login --poll, which waits for the approval and
saves the key:
string login --json
string login --poll{"verification_uri_complete":"https://…","user_code":"…","expires_in":600,"interval":5,"next":"string login --poll"}The code expires after expires_in seconds; run string login --json again for a new one. Without a terminal, or with
--no-wait, plain string login also prints the link and code and exits.
--env-file .env also writes the key to that file as its STRING_API_KEY line, without printing it. It works with
string login, --poll and --with-token. The file's other lines stay as they are, and a new file is readable only by
you. Given to string login --json, it carries over to the --poll that finishes the sign-in:
string login --json --env-file .env
string login --pollFetch a page
string fetch URL prints the page as Markdown. A URL on its own does the same.
string fetch https://example.com
string https://example.com --mainContentOnly -o example.md
string fetch https://example.com --format json--format json returns the full fetch response: the destination's status code, headers,
final URL and the page in data. --format raw returns the response bytes. A field that only the JSON response
carries, such as --jsonSchema or --screenshot, makes JSON the default. fetch sends a GET. To send a POST, PUT
or PATCH, use string request; for DELETE, HEAD or OPTIONS, call the
fetch API directly.
Commands
Search
string search QUERY prints the search response as JSON.
string search "web scraping with python" --searchCount 20
string search "coffee grinders" --dateRange week --sortBy date
string search "what is example.com" | jq -r '.results[] | "\(.title)\t\(.url)"' | head -2domain name - www.example.com vs example.com https://serverfault.com/questions/38387/www-example-com-vs-example-com
example https://en.wikipedia.org/wiki/.exampleWithout --searchCount, a search returns one page of results. With it, the search reads further pages until it has
that many; see Result count and paging. --count is the same
flag.
Send a POST, PUT or PATCH
string request METHOD URL sends a body to a URL and prints the same JSON as fetch --format json. It takes the
same fields as fetch.
string request POST https://httpbin.org/post --body '{"name":"example"}' --headers '{"Content-Type":"application/json"}'
string request PUT https://httpbin.org/put --body-file body.jsonThe first command prints the destination's answer, trimmed here:
{
"statusCode": 200,
"headers": { "content-type": ["application/json"] },
"data": { "json": { "name": "example" }, "url": "https://httpbin.org/post" },
"finalUrl": "https://httpbin.org/post"
}Crawl a site
string sitemap submit URL quotes a crawl of the site's URLs and costs nothing. Approving the quote holds its cost
against your balance and starts the crawl; Pricing says how the hold settles.
--approve approves as soon as the quote comes back, and --wait waits for the crawl to end:
string sitemap submit https://example.com --maxPages 50 --approve --waitOn a terminal, --wait keeps one progress line on stderr:
Crawling: 18 pages done, 6 queuedWhen the crawl ends, the CLI prints the job's final status as JSON, trimmed here:
{
"jobId": "6f1c9f0a-…",
"status": "completed",
"pagesProcessed": 50
}Pass its jobId as JOB_ID to read the URLs the crawl found:
string sitemap results JOB_ID --limit 100 --offset 0To see the price before you approve, submit without --approve and approve the job yourself:
string sitemap submit https://example.com --maxPages 500{
"jobId": "6f1c9f0a-…",
"status": "awaiting_approval",
"estimatedCostUsd": "0.0500000000",
"estimatedPages": 500
}Approve with the quote's jobId as JOB_ID; the other job commands take the same ID:
string sitemap approve JOB_ID --wait
string sitemap status JOB_ID
string sitemap list
string sitemap cancel JOB_IDStopping --wait with Ctrl+C leaves the crawl running; string sitemap status JOB_ID --wait waits for it again.
--maxPages, --maxDepth and --pathPrefix narrow the crawl and its quote. The fields, and how long a quote stays
open, are on the sitemap reference.
Site integrations
A site integration is a set of typed actions over one website, such as Reddit's post, search and
subreddit. string integrations lists every site and its actions, and string integrations list SITE prints each of
the site's actions with its flags, which ones are required, and an example. Listing needs no key.
string integrations
string integrations list redditstring integrations list reddit prints each action like this one, trimmed to the subreddit action:
string integrations run reddit subreddit
List a subreddit's posts in the order Reddit shows them: hot, new, top, rising, controversial or best, ...
--subreddit TEXT
(required) The subreddit: its name, such as technology, r/technology, or its URL. ...
--maxPages N
The most listing pages to read, 1 to 40, ... Defaults to 5 (about 100 posts)
--sort hot|new|top|rising|controversial|best
hot (the default), new, top, rising, controversial or beststring integrations run SITE ACTION calls the action and prints its JSON response. It needs a key.
string integrations run reddit subreddit --subreddit technology --sort new --maxPages 1{
"envelopeVersion": 1,
"integration": { "site": "reddit", "action": "subreddit", "version": "1.3.0" },
"data": [{ "title": "An example post", "subreddit": "technology", "score": 42, "commentCount": 7 }],
"failures": []
}The response is trimmed to a few fields of one row; Responses & errors lists every field.
Each flag is a field of the action's input, spelled exactly as the field. Reddit's subreddit action takes
subreddit, sort, time and maxPages, so its flags are --subreddit, --sort, --time and --maxPages, the
same names Reddit's page and its schema use. A list field takes one item per flag
(--items a --items b) or a JSON array. In the response, data holds the rows and failures lists any input that
produced none.
Most actions bill the requests they make, like fetches. The Reddit actions bill per row instead, and each post and
each comment is a row, so one large thread can cost far more than a fetch. Cap a per-row call with --maxPages. The
response's billing block shows how a call was charged, and
site integrations pricing has the rates.
Check your balance
string status shows the version and the key in use. With a key, it adds your organization's balance, any amount held
for crawls still running, the plan and its request rate, and auto top-up. Without a key, it shows what the last keyless
call from this machine left of today's allowance, so checking spends none of it.
string statusstring 0.2.0
Key none, so fetch and search run keyless
Keyless 48 requests and 98 credits left today, as of this machine's last keyless call at 18:22 UTCstring status --json prints the same as one JSON object. string balance prints your organization's
balance as JSON, with the amount left in USD in remaining. It needs
a key, and unlike status it exits nonzero when the balance can't be read, so a script can rely on its output:
string balance | jq .remainingSet up coding agents
string init installs the CLI's agent skill, which teaches a coding agent the string commands, for the coding
agents it finds on this machine. It always installs it in ~/.agents/skills, and also for Claude Code, Cursor, Gemini
CLI, OpenCode, GitHub Copilot, Windsurf, Goose, Droid, Kiro CLI, Qwen Code, Grok Build, OpenClaw and Hermes Agent when
their configuration directory exists. Run it again after an upgrade to update the skill.
string init
string init --agent claude-code,codexinit also adds the hosted MCP server to Claude Code and Codex, as string, unless
the server is already there or another server has that name. An entry for it under another name stays as it is, and
init prints that name to use in place of string. Both sign in to it with String, so no key goes into their
settings. Finish with:
claude mcp login string
codex mcp login stringFor the other agents it finds, init prints a link to the MCP setup page instead. --no-mcp skips the MCP step. When
you run init at a terminal with no key set, it then starts string login, and --no-login skips that.
API fields as flags
Each request field of /v1/fetch, /v1/search and
/v1/sitemap is a flag of the same name: executeJS is --executeJS, and
countryCode is --countryCode DE. The command sets url, query and method from its arguments, and string request
sets body from --body or --body-file.
string fetch https://example.com --executeJS --countryCode DE
string fetch https://example.com --jsonSchema @./schema.json
string fetch https://example.com --followRedirects=false --format json- A boolean flag on its own is true, and
=falseturns it off. - An object or array field takes JSON, or
@and a file path. --input FILEreads more fields from a JSON object, or--input -from stdin. Flags win over it, and the command's URL, query and method win over both.string fetch --help,string search --helpandstring sitemap --helplist each command's fields. A near miss such as--max-redirectsgets the right name back.
Output
| Command | Prints |
|---|---|
fetch | The page as Markdown, or JSON or raw bytes with --format |
search, request, sitemap, integrations run, balance | JSON |
integrations, status | Text, or JSON with --json |
--output FILE, or -o FILE, writes the response to a file instead of stdout. Notes, such as the keyless allowance,
and errors go to stderr, so stdout holds only the response.
Environment variables
| Variable | Effect |
|---|---|
STRING_API_KEY | The API key to use. It wins over a key saved by string login. |
XDG_CONFIG_HOME | Where the CLI keeps its files, in a string folder. Default: ~/.config. |
STRING_INSTALL_DIR | Where install.sh puts the binary. Default: ~/.local/bin. |
STRING_VERSION | The release tag install.sh installs, such as v0.2.0. Default: the latest release. |
Errors and exit codes
An error goes to stderr, followed by Retry-After, the keyless allowance and the x-request-id header when the API
sends them, then the next step. Without a key, for example:
string fetch https://example.com --countryCode DE`--countryCode` needs a key. Without a key, string fetch accepts only url, format, executeJS.
Next: run `string login` or set STRING_API_KEYAdd --json to any command to get the error as one JSON object on stderr instead. When the API sends code,
retryable or next_actions, they are passed through:
{"error":{"code":"key_required","help_url":"https://usestring.ai/auth.md","message":"`--countryCode` needs a key. Without a key, string fetch accepts only url, format, executeJS.","next_step":"run `string login` or set STRING_API_KEY","retry_after_seconds":null}}Branch on the exit code:
| Exit | Meaning | What to do |
|---|---|---|
0 | Success | |
1 | Any other failure, such as a network error or a failed crawl | Read the message. |
2 | Bad input or usage, or another 4xx from the API, such as 400 | Fix the flag or field the message names, and don't retry as is. The exception is a 409 with partial_state from string sitemap approve or string sitemap status: the approval didn't complete, so run string sitemap approve JOB_ID --wait again. string sitemap list shows the job. |
3 | Needs a key, or the key was refused: a field or command that needs a key, a keyless refusal, 401 or 403 | Without a key, sign in or drop the field. A 401 with a key means the key is wrong; string whoami says which one is in use. A 403 with a key names what your organization can't access. |
4 | 402: the balance is too low | Add funds under Usage & Plans, then retry. |
5 | 429: rate limited | Wait for Retry-After, then retry. |
6 | 5xx: the request failed, such as a page that couldn't be read | Retry once, then see Errors. |
7 | Timeout | Retry. |
130 | Interrupted with Ctrl+C |
Troubleshooting
- In fish,
stringruns the shell's own built-instringcommand. Run the CLI ascommand string, such ascommand string fetch https://example.com. - If your shell can't find
stringafterinstall.sh, add~/.local/bin, or yourSTRING_INSTALL_DIR, to yourPATH.
See also
- Authentication: the keyless allowance and API keys
- Remote (hosted) MCP: String in an MCP client
- Site integrations: every site and action
- The CLI's source and releases