Use String Web Access from a terminal. The CLI supports fetch, search, direct HTTP requests, and sitemap jobs. Responses go to stdout, so they can be piped to other commands.
It works without a key. Once string is installed, string fetch and string search run keyless, within a daily allowance per IP address, so the first call needs no account:
string search "string web access"
string https://example.comFor more, and for request and sitemap, sign in with string login or set STRING_API_KEY.
Pick whichever fits. Each installs the same native binary, string.
# macOS and Linux: installs string and adds the skill to your coding agents
curl -fsSL https://raw.githubusercontent.com/usestring/cli/main/install.sh | sh
brew tap usestring/cli https://github.com/usestring/cli && brew install usestring/cli/string
# Docker, e.g. in CI (pass -e STRING_API_KEY to use a key)
docker run --rm ghcr.io/usestring/cli search "your query"
# Anywhere with Node.js, once npm serves 0.2.0: installs string, adds the skill and signs you in
npx -y @usestring/cli init # or: npm install -g @usestring/cli# Windows, in PowerShell: installs string and adds the skill to your coding agents
irm https://raw.githubusercontent.com/usestring/cli/main/install.ps1 | iex
scoop bucket add usestring https://github.com/usestring/cli; scoop install stringUntil npm view @usestring/cli version prints 0.2.0 or later, npx -y @usestring/cli and npm install -g @usestring/cli get 0.1.0, the old Node CLI, which needs STRING_API_KEY and has none of the commands here.
Homebrew and Scoop install the release's own binary, so neither needs Go. If an npm installation already provides string, remove it with npm uninstall -g @usestring/cli first; each provides the same command. Upgrade with brew update && brew upgrade usestring/cli/string, or with scoop update scoop string.
install.sh and install.ps1 put the binary in ~/.local/bin, or %USERPROFILE%\.local\bin on Windows. install.ps1 adds that directory to your PATH, and install.sh prints the line that adds it in zsh, bash or fish. Each checks the binary against the release checksums, then runs string init so your coding agents get the skill below. They download from https://cli.usestring.ai, and from the GitHub release whenever that host cannot serve the release. STRING_VERSION, such as 0.3.0, installs that release instead of the latest and keeps the copy at it, and STRING_INSTALL_DIR puts the binary somewhere else. Pass init options after sh -s --, or --no-init to skip it. irm | iex takes no options, so in PowerShell set $env:STRING_NO_INIT = 1 or $env:STRING_INIT_AGENT first, or run a saved install.ps1 with -NoInit, -Agent, -Version and -InstallDir.
Each GitHub release also has the binaries for macOS, Linux and Windows, and .deb, .rpm and .apk packages for Debian, Fedora and Alpine. The packages are not signed yet, so rpm -i and a plain apk add refuse them. Install one with these commands from the directory you saved it in, with arm64 in place of amd64 on Arm:
sudo apt install ./string_*_linux_amd64.deb # Debian and Ubuntu
sudo dnf install ./string_*_linux_amd64.rpm # Fedora
apk add --allow-untrusted ./string_*_linux_amd64.apk # Alpine, as rootWithout a key, fetch and search go to the keyless tier. Each IPv4 address, or IPv6 /64, gets 50 requests and 100 credits per UTC day: a plain fetch costs 1 credit, and a fetch with executeJS or a search costs 5. Keyless takes only --format and --executeJS on fetch, and --language, --dateRange, --sortBy, --safeSearch, --autocorrect and --verbatim on search. The CLI refuses anything else before sending it, and prints what is left of the allowance to stderr after each call.
A key lifts those limits and unlocks every option, request and sitemap. There are three ways to give the CLI one:
-
string loginprints a code and opens String in your browser. Once you approve, String creates a new API key for that sign-in and the CLI saves it in~/.config/string/credentials.json(under$XDG_CONFIG_HOMEwhen that is set), readable only by you.string initruns it for you when no key is set, unless you pass--no-login: from a terminal it waits for your approval, and when its output is captured, as under a coding agent outside CI, it prints the link and code asstring logindoes there. If that sign-in doesn't finish, init still succeeds and says how to sign in later. Without a terminal, as under a coding agent, or with--no-wait,string loginprints the link and code and exits at once;string login --pollthen waits for the approval and saves the key. Add--jsonto get both as JSON:string login --json # {"verification_uri_complete":"…","user_code":"…","expires_in":600,"interval":5,"next":"string login --poll"} string login --poll # after the person approves
Add
--env-file .envtostring login, to--pollor to--with-tokento also write the key to that file as itsSTRING_API_KEY=line, without printing it. Every other line stays as it was, and a new file is created readable only by you.When it asks for the key,
string loginsends String a name for the machine it runs on: its system and the first part of its hostname, as inMac · work-laptop. String puts it in the name of the key it creates,String CLI · Mac · work-laptop, so your organization's API keys page shows which machine holds which key. To send another name, add--device-name NAME, of up to 51 characters, tostring login, to--no-waitor--poll, or tostring init.string login --browserand--with-tokensend no name.string login --browserneeds no code. It prints a link to a String page, and opens it when it can; there you sign in or create an account and click Authorize. The link works for 15 minutes.--no-wait,--poll,--jsonand--env-filework with it as above, andstring init --browsersigns in the same way. -
string login --with-tokenreads a key from String's API keys page on stdin, checks it with one free API call, and saves it in the same file. The key stays out of your shell history:string login --with-token < key.txt. -
STRING_API_KEYin the environment. It wins over a saved key, and the CLI never writes it to a file:export STRING_API_KEY="your-api-key"
string whoami shows which key commands use, and string logout deletes the saved one.
An agent working with nobody present can register for a trial key instead, where the server offers it. string trial solves a few seconds' proof of work and saves a key with a small balance in the same file. The key doesn't expire; it works until its credit runs out. Beside it, in trial.json, it keeps a claim token, which a person can use for 7 days to adopt the agent onto their String account. Neither is printed. Where trial keys are switched off, string trial exits 3.
string trial claim --email ADDRESS starts that claim. It prints a link and a code for the person at that address, who signs in to String with that email and enters the code. The CLI then saves a key on their account in place of the trial key, which stops working, and deletes trial.json. Without a terminal, or with --no-wait, it prints the link and code and exits, and string trial claim --poll waits for the person and saves the key. --json gives both as JSON.
string status shows the version and the key in use. With a key, it adds the balance left, any amount held for crawls still running, the plan and its request rate, and auto top-up. Without one, it shows what the last keyless call from this machine left of today's allowance, kept in ~/.config/string/keyless.json, so checking spends none of it. --json gives the same as one JSON object.
string balance prints the account's balance as JSON, exactly as GET /account/balance returns it, including remaining, held, exhausted, asOf, the plan and autoTopUp. It needs a key. string status still exits 0 when it can't read the balance; string balance fails with one of the exit codes instead, so a script can rely on its output:
string balance | jq .remainingCGO_ENABLED=0 go build -trimpath -o string ./cmd/string
go test ./...string https://example.com # the page as Markdown
string https://example.com --mainContentOnly -o example.md
string fetch https://example.com --format json # the full response: status, headers, final URL
string search "coffee shops in Austin" --searchCount 20
string search "coffee grinders" --dateRange week --sortBy date
string request POST https://example.com/api --body '{"name":"example"}' --headers '{"Content-Type":"application/json"}'Every API field is a flag of the same name. A field from the API reference works on the command line as written: executeJS is --executeJS, and countryCode is --countryCode DE. A boolean flag alone is true, and =false turns it off (--solveCaptcha=false). An object or array field takes JSON, or @ and a file path (--jsonSchema @./schema.json). string fetch --help, string search --help and string sitemap --help list each command's fields, and a near miss such as --max-pages gets the right name back.
fetch prints the page as Markdown. --format json gives the full response with the status, headers and final URL, and --format raw gives the response bytes. A field that only JSON carries, such as --jsonSchema or --screenshot, makes JSON the default. request, search and sitemap print JSON. --output FILE, or -o FILE, writes the response to a file instead.
--input FILE reads more fields from a JSON object, or --input - from stdin, and flags win over it. The command's URL, query and method win over both.
A sitemap crawl starts with a quote, which costs nothing. --approve starts the crawl at the quoted cost, and --wait waits for it to finish, with a progress line on a terminal:
string sitemap submit https://example.com --maxPages 50 --approve --wait
string sitemap results JOB_ID --limit 100 --offset 0Step by step, the same crawl is:
string sitemap submit https://example.com --maxPages 50 # the quote
string sitemap approve JOB_ID --wait
string sitemap status JOB_ID
string sitemap list
string sitemap cancel JOB_IDInterrupting --wait leaves the crawl running, and string sitemap status JOB_ID --wait picks it back up.
A site integration is a set of typed actions over one website. For example, reddit post reads a post with its whole comment tree, and yelp business reads business records. An action takes an input and returns rows in a fixed shape. Most actions bill the requests they make, like fetches. Some bill per row returned instead: the Reddit actions do, 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 the action's paging or limit flag, such as --maxPages on reddit post. The response's billing block shows how a call was charged, and the pricing page has the rates.
string integrations # every site and its actions; no key needed
string integrations list reddit # reddit's actions, each with its flags and an example
string integrations run reddit post --post https://www.reddit.com/r/technology/comments/1xapaw7/ --maxPages 2Each flag is a field of the action's input, spelled exactly as the field. Reddit's post action takes post, sort and maxPages, so its flags are --post, --sort and --maxPages, the same names the integration docs and the manifest use. A list field takes one item per flag (--items a --items b) or a JSON array. run prints the JSON response: data holds the rows, and failures lists any input that produced none. list needs no key; run needs one.
string --help lists the commands and the STRING_API_BASE_URL setting for a different API endpoint.
Errors go to stderr, followed by the Retry-After, keyless allowance and x-request-id headers when the API sends them, and the next step. Add --json to any command to get the error as one JSON object on stderr instead:
{"error":{"status":429,"code":"keyless_refused","message":"…","retry_after_seconds":3600,"request_id":"…","next_step":"run `string login` or set STRING_API_KEY","help_url":"https://usestring.ai/auth.md"}}When the API sends code, retryable or next_actions, they are passed through.
| Exit | Meaning |
|---|---|
| 0 | OK |
| 1 | Any other failure, such as a network error |
| 2 | Bad input or usage |
| 3 | Needs a key, or the key was refused (401, 403, or a keyless refusal) |
| 4 | Out of credit (402) |
| 5 | Rate limited (429) |
| 6 | Upstream failure (5xx) |
| 7 | Timeout |
| 130 | Interrupted |
string update # the latest release
string update --version 0.3.1 # exactly this release, kept until a plain string update
string update --check # the version, the latest release, and whether this copy updates itselfFrom 0.3.0, string update puts the latest release in place of the binary that runs it, once the release's signature and checksum check out. Homebrew, npm and Scoop keep track of the copies they installed, so for one of those string update changes nothing and prints the command that updates it, such as brew upgrade usestring/cli/string. --check --json gives the same report as one JSON object.
A copy that the install script installed checks for a new release once a day and installs it in the background after a command has finished, without changing that command's output or exit code. The next command run at a terminal says it did. Any other copy only says, at a terminal, that a release is out and how to update. The daily check asks https://cli.usestring.ai/stable which release is the latest, and fetches a release's manifest, signature and archive from the same host only to install it. Each request carries the version of string, the system and the CPU type in its User-Agent, as in string/0.3.0 (linux; amd64), and nothing else: no key, no account and nothing about the machine.
STRING_AUTO_UPDATE=0 (or false, off, no) turns off everything string does by itself: the daily check, the background install, the notices and the skill refresh. string update still works when you run it, and string init refreshes the skill by hand. A CI variable turns them off too, unless it is false or 0. The Docker image sets STRING_AUTO_UPDATE=0, since every run in a fresh container would otherwise look like the first of the day.
skills/string-cli is an Agent Skills skill that teaches a coding agent the string commands. The native binary carries it, and string init installs it into ~/.agents/skills (read by Codex and others) and into every agent it finds on the machine: Claude Code, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Goose, Droid, Kiro CLI, Qwen Code, Grok Build, OpenClaw and Hermes Agent. Run it again after an upgrade to update the skill.
The first command of a new release also rewrites the skill wherever it is already installed, however string was installed, and never installs it anywhere new.
string init # the shared directory and every agent found
string init --agent claude-code,codex # only these
string init --no-login # without signing in, even at a terminal
npx skills add usestring/cli # the same skill through the skills installerstring init also adds String's 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, such as string-web-access, stays as it is, and init prints that name for you to use in place of string. Both sign in to it with String, so no key goes into their settings: run claude mcp login string or codex mcp login string and choose the key each may use. For the other agents it found, init prints the setup page instead: most connect with an API key, which init never copies into another program's settings, and OpenCode signs in only from v2. --no-mcp skips this step.
usestring/cli is the canonical upstream for the native CLI, npm client, source releases, issues, the Homebrew formula and the Scoop manifest. CLI maintainers own release publication, and the release workflow updates the formula and the manifest; see releasing the CLI.