askfaro-cli 0.4.0

CLI for Faro: the tools your AI agent can't run on its own

askfaro-cli

Command-line interface for Faro: the tools your AI agent can't run on its own.

Two surfaces in one tool:

• Buyers — search for skills by natural language and run them from the terminal or any agent that can run shell commands.
• Publishers — create namespaces, edit listings declaratively in faro.yaml, and submit for review without leaving the shell.

Agent-readable reference: the canonical, always-current CLI docs live at https://askfaro.com/llms/cli.md. The full discovery index is at https://askfaro.com/llms.txt. You can also fetch any of these from the terminal:

askfaro docs              # full inlined docs (llms-full.txt)
askfaro docs cli          # this CLI reference
askfaro docs skill        # the buyer agent recipe
askfaro docs --list       # all available topics

Install

pip install askfaro-cli

Quick start

# Save your API key
askfaro auth login

# Search for a skill
askfaro search "generate an image"

# Run it (the skill agent picks the tools, runs them, and bills your account)
askfaro run image "a red bicycle"

Commands

askfaro auth login

Save credentials to ~/.config/faro/credentials (mode 0600). Three modes:

# Email + password — logs in, mints a new API key, saves it. JWT is discarded.
askfaro auth login --email [e-mail]

# Paste an existing key
askfaro auth login                          # interactive prompt
askfaro auth login --api-key faro_yourkey   # non-interactive

The --email flow is the recommended bootstrap for new machines. API keys cannot mint other keys (a leaked key must not be able to bootstrap replacements), so all key creation goes through this flow.

askfaro tokens list / askfaro tokens revoke <id-or-name>

List or revoke your API keys. Works with a saved API key (no password re-prompt) so emergency revocation is one command away. To mint a new key, use askfaro auth login --email.

askfaro tokens list
askfaro tokens revoke cli-mylaptop-20260101

askfaro auth whoami

Show the currently authenticated user.

askfaro auth logout

Remove the saved API key.

askfaro search <query>

Semantic search over the Faro catalog. Each hit carries enough to act on it without a second lookup (id, schema, pricing); a skill hit's id is what you hand to askfaro run.

askfaro search "transcribe audio"
askfaro search "weather forecast" --top 5 --category data

askfaro describe <namespace>/<tool>

Show the full schema and pricing for a single tool.

askfaro describe acme/send-email

askfaro run <skill> [prompt]

Run a skill end-to-end. The hosted skill agent selects the underlying tools, runs them, enforces your budget, and bills your account; you get back the normalized envelope. The intent is a prompt string or a JSON object (string, --intent, --intent-file, or piped stdin).

# Prompt shorthand
askfaro run image "a red bicycle"

# JSON intent
askfaro run image --intent '{"prompt": "a red bicycle", "size": "1024x1024"}'

# Stdin
echo '{"prompt": "a red bicycle"}' | askfaro run image

# Budget ceilings: hard cap, and a soft cap that returns a quote instead of spending
askfaro run image "a red bicycle" --max-credits 200 --confirm-above 50

A run that would cross --confirm-above comes back as a quote (status: needs_input) with a continuation token; re-run with --continuation <token> to proceed.

askfaro credits balance / askfaro credits purchases

Check your prepaid credit balance and purchase history. Agents should call askfaro credits balance before running expensive skills.

askfaro credits balance

askfaro docs [topic]

Fetch the agent-readable docs from askfaro.com. Renders markdown on a TTY; pipes raw markdown otherwise. Topics: quickstart, skill, search, invoke, cli, publish, or a <namespace> / <namespace>/<tool> for live listing docs.

askfaro docs                  # full llms-full.txt
askfaro docs skill            # buyer agent recipe
askfaro docs grok/web_search  # tool docs (markdown mirror of the listing)
askfaro docs --url cli        # print the URL only

askfaro doctor

One-shot health check: API key found, authenticated, publisher registered, namespace count.

askfaro doctor

---

Publishing a listing

The fastest path is the declarative faro.yaml workflow:

# 1. Become a publisher (one time)
askfaro publisher register --display-name 'Acme Corp'

# 2. Scaffold a namespace from your MCP server
askfaro ns quick-setup --namespace acme --mcp-url https://mcp.acme.dev

# 3. Pull a manifest you can edit
askfaro init acme            # writes ./faro.yaml + ./README.md

# 4. Edit faro.yaml — descriptions, tags, per-tool example_prompts.
#    Add `icon_file: ./logo.png` to upload + link the icon on push.
$EDITOR faro.yaml

# 5. Validate, preview, push, and submit
askfaro ns check acme        # local readiness check (mirrors server)
askfaro diff                 # preview manifest vs. server
askfaro push --publish       # save listing draft + submit for review

For one-off updates without the manifest, every API endpoint has a CLI counterpart:

Action	Command
List namespaces	askfaro ns list
Inspect a namespace	askfaro ns get <slug>
Edit description / tags	askfaro ns edit-listing <slug> --description '…' --tags 'a,b'
Set per-tool description / prompts	askfaro ns edit-listing <slug> --tools-file tools.json
Toggle a tool's visibility	askfaro ns tools set-visibility <slug> <tool_id> --visibility public
Add a REST tool by hand	askfaro ns tools add-rest <slug> --name search --method GET --path /search
Set group pricing	askfaro ns groups set-pricing <slug> <group_id> --mode fixed_per_request --fixed-cost 10
Store upstream API key	askfaro ns creds set <slug> --api-key '…'
Submit for review	askfaro publish <slug>
Earnings & sales	askfaro publisher earnings, askfaro publisher sales --period last_month

Every namespace argument accepts a slug or a UUID. Run faro <command> --help for examples on any individual command.

faro.yaml shape

namespace: acme
namespace_id: 5f6f1234-…
listing_name: Acme MCP
description: |
  Multi-line description rendered as `|` block scalars on round-trip.
category: developer-tools
tags: [email, comms]
icon_file: ./logo.png       # uploaded on `askfaro push` → URL stored back here
readme_file: README.md       # contents become the listing's readme_content
tools:
  - id: 1d…                  # UUID is required to update an existing tool
    name: send-email         # informational
    visibility: public
    short_description: Send an email
    display_order: 0
    example_prompts:
      - Send Bob a status update
      - Email everyone in marketing

For active namespaces, edits land on a server-side draft overlay until you publish.

---

Global options

Option	Env var	Description
--api-key	FARO_API_KEY	Faro API key
--api-url	FARO_API_URL	Override API base URL (default: https://api.askfaro.com)
--pretty / --json	—	Force pretty or JSON output (auto-detected by TTY)
-v / --verbose	—	Log HTTP requests to stderr

Authentication precedence

1. --api-key flag
2. FARO_API_KEY environment variable
3. ~/.config/faro/credentials

Exit codes

Code	Meaning
0	Success
1	General error
2	Auth error (invalid or missing key)
3	Not found
4	Validation error (bad parameters)
5	Quota / billing limit reached
6	Upstream tool error
7	Network / timeout error (retriable)

When stderr is a pipe (agent / script), errors are printed as JSON:

{"error": {"code": "quota_exceeded", "message": "...", "retriable": false}}

On a TTY they render as ✗ <message> so the JSON noise doesn't dominate.

---

Use Faro from your agent

Copy this system-prompt snippet to give any LLM shell access to Faro:

You have access to Faro (the tools your agent can't run on its own) via the `faro` CLI.

To find tools:
  askfaro search "<describe what you want to do>"
  Returns a JSON list. Each item includes `display_name` (use this to invoke),
  `short_description`, and `input_schema` (the exact parameters required).

To invoke a tool:
  faro invoke <display_name> --params '<json object matching input_schema>'
  Returns a JSON object with `result` (the tool output) and `status`.

Rules:
- Always search before invoking unless you already know the exact tool name.
- Pass all required fields from input_schema. Use --dry-run to validate first.
- If exit code is 7, retry once. If exit code is 5, tell the user they need more credits.
- Output JSON only; parse `result` for the tool's actual response.

Examples:
  askfaro search "send a slack message"
  faro invoke slackbot/send-message --params '{"channel": "#general", "text": "Hello"}'

Worked example — Claude API

import anthropic
import subprocess
import json

client = anthropic.Anthropic()

system = """
You have access to Faro (the tools your agent can't run on its own) via the `faro` CLI.
[paste the snippet above]
"""

def run_faro(command: str) -> str:
    result = subprocess.run(
        ["bash", "-c", f"faro {command}"],
        capture_output=True, text=True
    )
    if result.returncode not in (0,):
        return result.stderr  # error envelope JSON
    return result.stdout

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=system,
    messages=[{"role": "user", "content": "Send a Slack message to #alerts saying the deploy is done."}],
)

# The model will emit faro commands; run them and feed results back

Worked example — environment variable auth

export FARO_API_KEY=faro_yourkey

# In your agent's subprocess call:
result=$(askfaro search "translate text to Spanish" --json)
tool_name=$(echo $result | jq -r '.[0].display_name')
faro invoke "$tool_name" --params '{"text": "Hello world"}'

---

MCP vs CLI

	MCP	CLI
Setup	Config block in your host app	pip install askfaro-cli
Best for	Claude Desktop, Cursor, MCP-native hosts	Custom agents, Claude API, any shell
Discovery	Dynamic at connect time	askfaro search
Auth	API key in MCP config	FARO_API_KEY or askfaro auth login
Debuggable	Harder	Run the exact same command yourself

Both use the same API keys and the same tool catalog.