CLI reference
The findagent command-line tool installs agents, downloads departments, manages credentials, and signs your machine in. Every command and flag the CLI accepts is listed below, and findagent --help prints the same list offline.
findagent CLI is published on npm as @findagent/cli — run any command with npx @findagent/cli <command>, no global install needed. The web installer produces the same files if you'd rather stay in the browser.On this page
install
Install an agent into your LLM runtime.
install resolves instructions-only agents, local agents with actions, and agents made of skills to local files. A hosted code-bundle or hosted agent isn't installed locally — it runs in FindAgent's sandbox and resolves to Connect instead. An agent whose creator also offers a local option can be run on your own machine with --local.
findagent install <agent>[@version] [--llm <target>] [--dir <path>] [--dry-run] [--local | --hosted]
| Flag | Description |
|---|---|
--llm <target> | Target runtime: claude, chatgpt, gemini, cursor, vscode, or custom. Asked on a terminal; required in scripts and with --dry-run. |
--dir <path> | Project directory to install into (default: current directory). |
--dry-run | Print what would be written without touching the filesystem. |
--local | For an agent that can run hosted or locally: run it on your own machine. FindAgent never runs it there. |
--hosted | For an agent that can run hosted or locally: connect over the hosted gateway (the default). Pass either --local or --hosted, not both. |
findagent install atlas --llm claude
findagent install atlas@1.0.0 --llm cursor
download
Download a Department (a multi-agent team) to run locally.
findagent download <department> [--dir <path>] [--dry-run]
See Departments for running the downloaded team with @findagent/mcp run-department.
uninstall
Remove an installed agent's files (reverses install).
findagent uninstall <agent> [--yes] [--dry-run]
--yes skips the confirmation prompt; --dry-run lists what would be deleted without touching the filesystem.
info
Show an agent summary before installing. It writes nothing.
findagent info <agent>
lint
Validate a FindAgent manifest, or an Agent Plugins package (plugin.json or its directory), locally with no network access, so it works in CI. Pass a path, or leave it off to check the default manifest in the current directory; --json prints a machine-readable report.
findagent lint [path] [--json]
list
List the agents you have installed. Aliases: ls, installed.
findagent list
Authentication
findagent login— authenticate this machine via the browser device flow. Pass--token <jwt>to paste a token instead (useful in CI).findagent logout— remove the stored FindAgent credentials.findagent whoami— show the currently signed-in account.
Credentials (secrets)
Store and manage per-agent external credentials locally.
findagent secrets set <ref> [value]— store a credential for a manifest slot. Leave the value off and the CLI reads it from a hidden prompt (or from piped input, e.g.cat token.txt | findagent secrets set <ref>) so the secret never lands in your shell history.- Add
--agent <slug>tosecrets setorsecrets rmwhen two installed agents declare the same ref. findagent secrets host <ref> <host>— set the self-hosted target host for a slot that takes its host at install (for example a self-hosted GitLab domain).findagent secrets list— list stored credential refs (values hidden) and self-hosted target hosts.findagent secrets rm <ref>— remove a stored credential, and any self-hosted host for it.
Stored values never leave your machine and are only attached to requests whose host the slot allows — see the security model.
install sets up an agent's credentials, it prints the value format each slot expects — a bearer slot takes the raw token, a basic slot takes the Base64 of id:token, and a custom header slot takes the bare key. Following the printed hint avoids the common “pasted the raw token into a Basic-auth slot” mistake.Help & version
findagent --help
findagent --version