# Faro quickstart

One Faro account gives your agent the tools and data it can't run on its own: no per-provider signups, payments, or API keys. One Bearer token, three steps:

## 1. Get an API key

One call, email only, no password, no human:

```
POST https://api.askfaro.com/auth/agent-signup
Content-Type: application/json

{"email": "agent@yourdomain.com", "token_name": "my-agent"}
```

The response returns `api_key` (use it immediately) and `login_url` (hand to a human to manage billing and limits). The account starts unverified: self-hosted tools and a small free allowance work right away; clicking the verification email (or making any purchase) unlocks the full free data tier and paid tools. Re-send the link any time with `POST https://api.askfaro.com/auth/resend-verification`.

Prefer a console, or already have an account? Sign up at https://askfaro.com/register (email + password), then mint keys with `POST https://api.askfaro.com/tokens/` (Bearer JWT from `POST https://api.askfaro.com/auth/login`). Or, in a shell:

```
pip install askfaro-cli
askfaro auth login   # paste the faro_ key
```

## 2. Find a tool

Semantic search across all active namespaces:

```
GET https://api.askfaro.com/tools/search?q=find+the+ceo+of+a+company
```

Each hit includes `namespace`, `name`, `input_schema`, and `pricing`. No second lookup needed.

CLI equivalent:

```
askfaro search "find the ceo of a company"
```

## 3. Run a skill

A skill is the unit you run: hand it an intent, the hosted skill agent picks the underlying tools, runs them, enforces your budget, and bills you.

```
POST https://skill.askfaro.com/skills/{skill}/run
Authorization: Bearer faro_<your_key>
Content-Type: application/json

{"intent": { "prompt": "a red bicycle" }}
```

CLI:

```
askfaro run <skill> "<intent>"
```

The response is the canonical envelope: the result, credits charged, and your remaining balance.

## What's next

- [Skill recipe](https://askfaro.com/llms/skill.md), the loop an agent should follow.
- [Run reference](https://askfaro.com/llms/run.md), the envelope, errors, budget ceilings, partner tokens.
- [CLI reference](https://askfaro.com/llms/cli.md), every command.
