Felo Cli

Use this skill for any task that involves searching, querying external information, looking up current facts, checking dates, verifying public information, or otherwise retrieving information beyond the local workspace. This includes requests such as「幫我查一下…」、「搜尋…」、「最新資訊」、「今年是什麼時候」、「哪裡可以找到…」等。

Rule: if the user request is related to search in any way, prefer this skill first.

Prefer project tools in this order:

1. CLI: npx -y @willh/felo-cli --json "<query>" (always use --json when retrieving content so the full structured output is preserved). 2. SDK: createFeloClient() / feloChat() from src/felo-client.ts when programmatic integration is needed. 3. Direct API call only when validating protocol-level behavior.

For direct HTTP reference, use POST https://openapi.felo.ai/v2/chat with:

• Environment variable: FELO_API_KEY
• Authorization: Bearer <FELO_API_KEY>
• Content-Type: application/json
• Body { "query": "<string>" } where query is 1..2000 characters

Handle success/error payloads and rate-limit headers using references/api-contract.md and references/workflow.md.

Felo Chat API Contract Reference

This contract is aligned with the official docs at https://openapi.felo.ai/docs/api-reference/v2/chat.html.

Repository-first usage

For this repository, prefer the local tooling before direct HTTP calls:

1. CLI: npx -y @willh/felo-cli "<query>" or npx -y @willh/felo-cli --json "<query>". 2. SDK: createFeloClient() / feloChat() from src/felo-client.ts. 3. Use direct API contract details below when implementing/verifying low-level HTTP behavior.

Base URL

https://openapi.felo.ai

Endpoint

POST /v2/chat

Authentication

• Env var: FELO_API_KEY
• Required header: Authorization: Bearer <FELO_API_KEY>
• Required header: Content-Type: application/json

Request body schema

{
  "query": "What are the latest developments in quantum computing?"
}

Constraints:

• query is required.
• query must be a string with length 1..2000 characters.

Success response schema (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "id": "HabCj883yHLSXc8mWqu4Eq",
    "message_id": "18ea8517-5559-4f48-a355-1f8a79e73b71",
    "answer": "Recent developments in quantum computing include...",
    "query_analysis": {
      "queries": [
        "quantum computing latest developments 2025",
        "quantum computing breakthroughs"
      ]
    },
    "resources": [
      {
        "link": "https://example.com/quantum-news",
        "title": "Latest Quantum Computing Breakthroughs",
        "snippet": "Scientists have achieved a major milestone..."
      }
    ]
  }
}

Field meanings:

• status: "ok" on success.
• message: null on success.
• data.id: chat session ID.
• data.message_id: message ID.
• data.answer: generated answer text.
• data.query_analysis.queries[]: optimized queries.
• data.resources[]: cited sources with link, title, snippet.

Error response schema

{
  "status": "error",
  "code": "INVALID_API_KEY",
  "message": "The provided API Key is invalid or has been revoked",
  "request_id": "req_abc123xyz789"
}

Field meanings:

• status: always "error".
• code: machine-readable error code.
• message: human-readable error details.
• request_id: request identifier for support/debugging.

Rate-limit headers

Read these headers from responses:

• X-RateLimit-Limit: max requests per minute.
• X-RateLimit-Remaining: remaining requests in current window.
• X-RateLimit-Reset: Unix timestamp when the limit resets.

Documented default limit: 100 requests per minute per API Key.

Common error codes

For usage flow, see workflow.md.

Felo Chat API Workflow Reference

This workflow is aligned with the official docs at https://openapi.felo.ai/docs/api-reference/v2/chat.html.

0) Prefer repository tools first

In this codebase, default to repository interfaces before raw HTTP:

1. CLI: npx -y @willh/felo-cli "<query>" (answer only) or npx -y @willh/felo-cli --json "<query>" (full payload). 2. SDK: createFeloClient().chat(query) or feloChat(query) from src/felo-client.ts. 3. Raw API call only for protocol verification, troubleshooting, or SDK/CLI parity checks.

1) Preflight

1. Read FELO_API_KEY from environment. 2. Stop immediately if missing. 3. Validate query as a string with length 1..2000.

2) Send request

1. Use base URL https://openapi.felo.ai. 2. Call POST /v2/chat. 3. Set headers:

• Authorization: Bearer <FELO_API_KEY>
• Content-Type: application/json

4. Send JSON body:

{
  "query": "What are the latest developments in quantum computing?"
}

3) Parse success response (200)

Expect this schema:

{
  "status": "ok",
  "message": null,
  "data": {
    "id": "HabCj883yHLSXc8mWqu4Eq",
    "message_id": "18ea8517-5559-4f48-a355-1f8a79e73b71",
    "answer": "Recent developments in quantum computing include...",
    "query_analysis": {
      "queries": [
        "quantum computing latest developments 2025",
        "quantum computing breakthroughs"
      ]
    },
    "resources": [
      {
        "link": "https://example.com/quantum-news",
        "title": "Latest Quantum Computing Breakthroughs",
        "snippet": "Scientists have achieved a major milestone..."
      }
    ]
  }
}

Return data.answer, preserve data.id and data.message_id, and include data.resources.

4) Parse error response

Expect this schema:

{
  "status": "error",
  "code": "INVALID_API_KEY",
  "message": "The provided API Key is invalid or has been revoked",
  "request_id": "req_abc123xyz789"
}

Preserve status, code, message, HTTP status, and request_id exactly.

5) Respect rate limits

Read these response headers on every request:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

If the API returns 429 (RATE_LIMIT_EXCEEDED), back off and retry after reset.

6) Handle common error codes

Handle these documented codes: INVALID_API_KEY, MISSING_AUTHORIZATION, MALFORMED_AUTHORIZATION, MISSING_PARAMETER, INVALID_PARAMETER, QUERY_TOO_LONG, RATE_LIMIT_EXCEEDED, CHAT_FAILED, SERVICE_UNAVAILABLE.

For field-level details, see api-contract.md.