# askfaro-cli

`askfaro-cli` is the official command-line client. It wraps every API endpoint, outputs JSON when stdout is piped (agent-friendly), and uses stable exit codes for errors.

## Install

```
pip install askfaro-cli
```

Or bootstrap with no install:

```
npx askfaro <command>
```

## Authenticate

```
faro auth login --email you@example.com   # password prompt → mints + saves an API key
faro auth login                           # paste an existing key
```

Credentials live at `~/.config/faro/credentials`. You can also set `FARO_API_KEY` in your environment, or pass `--api-key` per-call.

API keys cannot mint other API keys; all key creation goes through the email+password flow. Use `faro tokens list` / `faro tokens revoke <id-or-name>` to manage existing keys.

## Buyer commands

```
faro search "<natural language query>"           # semantic search; returns JSON
faro describe <namespace>/<tool>                 # full input_schema + pricing + curl
faro invoke <namespace>/<tool> --params '<json>' # invoke with inline JSON
faro invoke <namespace>/<tool> --params-file args.json
echo '{"to":"a@b.com"}' | faro invoke <namespace>/<tool>
faro invoke <namespace>/<tool> --params '{...}' --dry-run   # validate against schema
```

Examples:

```
faro search "send an email"
faro describe acme/send-email
faro invoke acme/send-email --params '{"to":"user@example.com","subject":"Hi"}'
```

## Account commands

```
faro doctor              # check auth + publisher status + namespace health
```

## Publisher commands

```
faro publisher register --display-name 'Acme'
faro ns quick-setup --namespace acme --mcp-url https://mcp.acme.dev
faro init acme                  # writes faro.yaml + README.md
faro push --publish             # save manifest + submit for review
faro ns check acme              # local validation
faro pull acme                  # pull latest server state into faro.yaml
faro diff                       # show local vs server diff
```

## Output

- TTY: pretty-printed.
- Piped or `--json`: machine-readable JSON on stdout.
- Errors: JSON envelope on stderr, stable exit codes (`EXIT_AUTH`, `EXIT_VALIDATION`, `EXIT_NOT_FOUND`, `EXIT_API`, `EXIT_NETWORK`).

## Why CLI for agents

`faro search` returns each result with its `input_schema` already attached, so an agent can search → invoke in two shell calls. No second describe round-trip required unless you need long_description or examples.

## Source

- npm bootstrap: https://askfaro.com/cli (npx askfaro)
- PyPI: `askfaro-cli`