@findagent/cli

Install a cross-LLM AI agent into your editor in one command — from your terminal.

findagent is the command-line installer for the FindAgent cross-LLM agent marketplace. One command writes the exact files an agent needs into Claude, ChatGPT, Gemini, Cursor, or VS Code — recipe agents and tool-using "doer" agents alike — and the artifact is byte-identical to the guided web installer.

A FindAgent agent is a manifest, not a program: it describes its prompt and tools, and a single trusted runtime executes them — agents never ship code to run on your machine. No remote-code-execution surface, ever.

Quick start

# Sign this machine in (browser device flow), then install
npx @findagent/cli login
npx @findagent/cli install pr-reviewer

# …or install globally
npm i -g @findagent/cli

Requires Node ≥ 18.

findagent install [email protected] --llm cursor   # pin a version, target Cursor
findagent install pr-reviewer --dry-run            # preview writes, touch nothing

Commands

| Command | What it does | | --- | --- | | install <slug[@version]> | Install an agent into your LLM runtime. Flags: --llm <target>, --dir <path>, --dry-run. | | uninstall <slug> | Remove the files a previous install wrote (only those, only where they landed). Flags: --yes, --dry-run. | | info <slug[@version]> | Show an agent summary before installing — writes nothing. | | lint [path] | Validate a manifest locally against the marketplace's own schema. Flag: --json. Exit 0 = valid, non-zero = invalid. | | download <department> | Download a Department (a multi-agent team) to run locally. Flags: --dir, --dry-run. | | list  (ls, installed) | List agents you've purchased or installed. | | login | Authenticate this machine via the OAuth device flow. Flag: --token <jwt> to paste one instead. | | logout · whoami | Clear stored credentials · show the signed-in account. | | secrets set <ref> | Store a per-agent external credential (prints a per-scheme format hint). | | secrets list · secrets rm <ref> | List stored refs (values hidden) · remove one. |

Run findagent --help for the full flag reference.

--llm targets

| Target | Aliases | Lands in | | --- | --- | --- | | claude | claude-code | .claude/agents/ | | chatgpt | openai, gpt | .findagent/chatgpt/ | | gemini | google | .findagent/gemini/ | | cursor | — | .cursor/mcp.json | | vscode | vs-code, code | .vscode/mcp.json | | custom | generic | .findagent/ |

The target set is the canonical cross-LLM list shared with the marketplace and @findagent/schema (LLM_TARGETS) — the picker, the install bundle, and the CLI never drift. A recipe agent lands as a per-client file; a hosted/MCP agent lands as a ready mcpServers connector.

Credentials

If an agent calls an external service, its manifest declares credential slots. Store a value once — it never leaves your machine, is written owner-only (0600) in your OS config dir, and the runtime attaches it only to requests whose host the slot allows (audience binding). Prefer NOT passing the value as an argument — an inline secret lands in your shell history. Omit it and the CLI reads it from stdin (a hidden prompt on a terminal, or piped input):

findagent secrets set <ref>           # hidden prompt — keeps the secret out of shell history
cat token.txt | findagent secrets set <ref>   # or pipe it in
findagent secrets list                # refs only — values never printed
findagent secrets rm <ref>

It also prints the value format hint for the slot's auth scheme (Basic → Base64, custom header → the bare key).

The store is shared with the @findagent/mcp runtime.

Validate before you submit

findagent lint runs a manifest through the same validator the marketplace runs at submit time — so you catch errors on your machine and in CI, not after your agent enters the review queue. It's pure local validation: no network, no auth, nothing submitted. It covers every kind (recipe · doer · code-bundle · skills-bundle · department).

findagent lint                 # validates ./manifest.json
findagent lint agent.yaml      # .json / .yaml / .yml auto-detected
findagent lint manifest.json --json   # machine-readable report for CI

Exit code 0 means valid, non-zero means invalid (a human-readable list of each field path + message, or a JSON { ok, kind, issues[] } report under --json).

In GitHub Actions

Lint every manifest on push with the bundled composite action:

# .github/workflows/manifest.yml
name: Validate manifest
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx --yes @findagent/cli lint manifest.json

Configuration

| Env var | Default | Purpose | | --- | --- | --- | | FINDAGENT_API | https://beta.findagent.cloud | API base (override for staging). Must be https for any token exchange — a plaintext base is refused. | | NO_COLOR | — | Disable ANSI color. |

Credentials live in your OS config dir — ~/.config/findagent/auth.json (macOS/Linux) or %APPDATA%\findagent\auth.json (Windows).

How it works

The CLI and the web installer at /install/<slug> produce the identical artifact. Both call the same endpoint (GET /api/v1/agents/<slug>/install-bundle?llm=<target>), whose shape is the shared installBundleResponseSchema in @findagent/schema; the server renders the manifest + per-LLM files and the CLI writes the returned files[] verbatim.

• Paid-gated like the web flow — an unpurchased paid agent returns 402 and the CLI refuses, writing nothing.
• login runs an OAuth 2.0 Device Authorization Grant (RFC 8628): it prints a short user_code, opens /device, and completes the poll once you approve in the browser.
• uninstall reverses a previous install: it removes only the files that install recorded, only inside the directory they landed in — it never touches a file it didn't write, and confirms first (skip with --yes).

Links

• Marketplace — https://findagent.cloud
• Docs — https://findagent.cloud/docs/install
• Runtime — @findagent/mcp

License

MIT