String docs

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.

AI agent? Read https://usestring.ai/agent-onboarding/SKILL.md first. It gets you your own API key with one browser click, and fetch and search work with no key.

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.com

It 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.sh downloads the binary for your system from the latest GitHub release, checks it against the release's checksums.txt, and puts it in ~/.local/bin. Set STRING_INSTALL_DIR to install somewhere else, or STRING_VERSION to a tag such as v0.2.0 to install that release. It then runs string init; pass init options after sh -s --, or sh -s -- --no-init to 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, .rpm and .apk packages. On Windows, unzip string_windows_amd64.zip or string_windows_arm64.zip and put string.exe in a folder on your PATH.

  • The Docker image, ghcr.io/usestring/cli, runs one command per container. Pass -e STRING_API_KEY to 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.txt

Or 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 --poll

Fetch 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

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 -2
domain name - www.example.com vs example.com	https://serverfault.com/questions/38387/www-example-com-vs-example-com
example	https://en.wikipedia.org/wiki/.example

Without --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.json

The 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 --wait

On a terminal, --wait keeps one progress line on stderr:

Crawling: 18 pages done, 6 queued

When 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 0

To 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_ID

Stopping --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 reddit

string 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 best

string 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 status
string 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 UTC

string 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 .remaining

Set 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,codex

init 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 string

For 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 =false turns it off.
  • An object or array field takes JSON, or @ and a file path.
  • --input FILE reads 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 --help and string sitemap --help list each command's fields. A near miss such as --max-redirects gets the right name back.

Output

CommandPrints
fetchThe page as Markdown, or JSON or raw bytes with --format
search, request, sitemap, integrations run, balanceJSON
integrations, statusText, 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

VariableEffect
STRING_API_KEYThe API key to use. It wins over a key saved by string login.
XDG_CONFIG_HOMEWhere the CLI keeps its files, in a string folder. Default: ~/.config.
STRING_INSTALL_DIRWhere install.sh puts the binary. Default: ~/.local/bin.
STRING_VERSIONThe 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_KEY

Add --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:

ExitMeaningWhat to do
0Success
1Any other failure, such as a network error or a failed crawlRead the message.
2Bad input or usage, or another 4xx from the API, such as 400Fix 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.
3Needs a key, or the key was refused: a field or command that needs a key, a keyless refusal, 401 or 403Without 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.
4402: the balance is too lowAdd funds under Usage & Plans, then retry.
5429: rate limitedWait for Retry-After, then retry.
65xx: the request failed, such as a page that couldn't be readRetry once, then see Errors.
7TimeoutRetry.
130Interrupted with Ctrl+C

Troubleshooting

  • In fish, string runs the shell's own built-in string command. Run the CLI as command string, such as command string fetch https://example.com.
  • If your shell can't find string after install.sh, add ~/.local/bin, or your STRING_INSTALL_DIR, to your PATH.

See also