# 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

```
askfaro auth login --email you@example.com   # password prompt → mints + saves an API key
askfaro 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 `askfaro tokens list` / `askfaro tokens revoke <id-or-name>` to manage existing keys.

## Buyer commands

```
askfaro search "<natural language query>"           # semantic search; returns JSON
askfaro describe <namespace>/<tool>                 # full input_schema + pricing + curl
askfaro run <skill> "<intent>"                      # run a skill: intent in, result out
askfaro run <skill> --intent '<json>'               # structured intent
echo '{"prompt":"..."}' | askfaro run <skill>       # intent piped on stdin
askfaro run <skill> "<intent>" --max-credits 200 --confirm-above 50   # budget ceilings
```

The skill agent selects the underlying tools, runs them, and bills your account.
Raw vendor tools aren't directly runnable, by design: skills are the only surface,
each one a brief over the tools it needs.

Examples:

```
askfaro search "generate an image"
askfaro run image "a red bicycle"
askfaro run image "a red bicycle" --max-credits 200
```

## Account commands

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

## Publisher commands

```
askfaro publisher register --display-name 'Acme'
askfaro ns quick-setup --namespace acme --mcp-url https://mcp.acme.dev
askfaro init acme                  # writes faro.yaml + README.md
askfaro push --publish             # save manifest + submit for review
askfaro ns check acme              # local validation
askfaro 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

`askfaro search` returns each result with its `input_schema` already attached, so an agent can search → run 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`
