> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useagents.site/llms.txt
> Use this file to discover all available pages before exploring further.

# UseAgents CLI

> Install and use the UseAgents CLI to search the live registry, fetch tool context, and search docs.

The `useagents` CLI searches the live UseAgents registry, fetches implementation context, and searches a tool's official documentation from a terminal or script.

## Install with npm

```bash theme={null}
npm install --global @useagents/cli
useagents --help
```

The package exposes the `useagents` command and works with npm, pnpm, yarn, or Bun global installs.

## Install a standalone binary

On macOS or Linux, the installer detects your operating system and CPU architecture, verifies the SHA-256 checksum, and installs to `${XDG_BIN_HOME:-$HOME/.local/bin}`:

```bash theme={null}
curl -fsSL https://useagents.site/cli/install.sh | sh
useagents --help
```

If the command is not found, add the install directory to your `PATH`:

```bash theme={null}
export PATH="${XDG_BIN_HOME:-$HOME/.local/bin}:$PATH"
```

The binaries are published as GitHub Release assets. They are not stored in the web application repository. Set `USEAGENTS_VERSION=v1.2.3` to install a specific release. Windows users can install the npm package or download the Windows asset manually from the release page.

## Upgrade

Standalone binary installs can self-upgrade by re-running the official install script:

```bash theme={null}
useagents upgrade
useagents upgrade --release v0.1.8
```

`upgrade` runs `curl -fsSL https://useagents.site/cli/install.sh | sh`. Pass `--release` or set `USEAGENTS_VERSION` to pin a tag. Check the installed version with `useagents --version`.

If you installed via npm, upgrade with:

```bash theme={null}
npm install --global @useagents/cli@latest
```

Binary upgrades are not supported on Windows; use the npm package there.

## Search the registry

```bash theme={null}
useagents search "email API" --limit 5
useagents search "MCP server" --language typescript-javascript --transport mcp
```

Useful aliases include `-l` for `--language`, `-t` for `--transport`, and `-c` for `--category`.

## Fetch context

```bash theme={null}
useagents context resend
useagents context resend -l typescript-javascript -t api
```

Context includes the full description, source links, matching quickstarts, install steps, examples, and input/output guidance.

## Search documentation

```bash theme={null}
useagents docs resend "how do I send attachments"
useagents docs stripe "configure webhook signature verification"
```

Docs search resolves the tool's official docs URL from the registry and returns ranked passages for your question.

## Test a snippet in the sandbox

```bash theme={null}
useagents test \
  --runtime node \
  --language typescript \
  --package resend \
  --file src/index.ts \
  --slug resend
```

`--file` is relative to the current directory and may be repeated. `--package` and `--env NAME=value` are also repeatable. The CLI POSTs to [`/tools/test`](/api-reference/tools-test) and exits `1` when `ok` is false. The sandbox allows outbound network so live vendor API calls can run; pass keys with `--env`. JavaScript and TypeScript (`--runtime node`) use the Bun runtime to add packages and run files. Reuse a previous sandbox with the `sessionId` from the last result. The box is paused between runs and has no hard TTL.

## Output formats

| Format    | Flag                        | Default      |
| --------- | --------------------------- | ------------ |
| **human** | `--format human`            | TTY sessions |
| **json**  | `--format json` or `--json` | Piped stdout |
| **toon**  | `--format toon`             | Opt-in       |

`--format` wins over `--json` and over the pipe default. Structured success uses one envelope per command (`command`, `query`, `data`, `meta`). Progress output, if enabled, is sent to stderr.

```bash theme={null}
useagents search "email" --json | jq '.data.results[] | .slug'
useagents docs resend "attachments" --format toon
```

See [Response formats](/api-reference/response-format) for how API and MCP defaults differ.

Run `useagents --help`, `useagents search --help`, `useagents context --help`, `useagents docs --help`, `useagents test --help`, or `useagents upgrade --help` for all flags.