> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> ## Agent Instructions (AIsa)
>
> - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative.
> - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key.
> - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste.
> - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`.
> - Paid calls need approval first. Docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP discovery are free to read. Before any paid, dynamically priced, or high-cost call, state the exact scope, rate, and maximum USD exposure, then wait for a separate user message approving that scope and cap. A request to collect data is not approval; do not send unapproved probes. Full rule: https://aisa.one/docs/llms.txt

# Use the AIsa CLI

> Install @aisa-one/cli, sign in with your browser, and search, quote, and call AIsa tools from a terminal, script, or CI job.

The AIsa CLI gives terminals, scripts, and CI the same catalog an agent reaches through MCP, plus model chat, balance, and usage. Use it when an MCP client is not available; otherwise [Connect via MCP](/docs/agent-quickstart).

<Steps>
  <Step title="Install">
    ```bash theme={null}
    npm install -g @aisa-one/cli
    aisa --version
    ```

    Requires Node.js 18 or later.
  </Step>

  <Step title="Sign in">
    ```bash theme={null}
    aisa login
    aisa balance
    ```

    `aisa login` opens a browser and stores an auto-refreshing OAuth session; there is no key to copy. `aisa balance` proves the sign-in worked. For CI and other headless jobs, set `AISA_API_KEY` instead (or run `aisa login --key <key>`); it takes precedence over the stored session.
  </Step>

  <Step title="Ask your agent">
    Paste this into the coding agent that runs in this terminal:

    ```txt wrap theme={null}
    Use the aisa CLI to find three recent public updates about a company of your choice with source links. Run aisa search first and quote before any paid call; ask me before running it.
    ```
  </Step>
</Steps>

## Commands

| Command | What it does | Billed |
| - | - | - |
| `aisa search "<task>"` | Find tools for a task in plain language | Free |
| `aisa schema <tool>` | Full input schema of a tool | Free |
| `aisa quote --input '<calls>'` | Price a call without running it | Free |
| `aisa call --input '<calls>'` | Run one or more tool calls | Per call |
| `aisa chat "<message>" --model <id>` | Chat with any model in the catalog | Per token |
| `aisa models` | List model IDs | Free |
| `aisa balance` / `aisa usage` | Balance and daily usage | Free |
| `aisa skills install <name>` | Install a skill from the [catalog](/docs/agent-skills) | Free |

```bash theme={null}
aisa search "company facts" --json
aisa quote --input '{"calls":[{"call_id":"c1","tool":"<name from search>","arguments":{}}]}' --json
```

`quote` and `call` accept the same input, so you can review an estimate and run exactly that request. Quotes are free, never execute anything, and are not approval. Run `aisa --help` or `aisa <command> --help` to see all flags.

## Agent rules for the CLI

**Gate:** use the CLI only when this client has no MCP mechanism, the task is non-interactive automation with an existing key, or the user explicitly chose the CLI.

Node.js **must already be installed** — otherwise stop; use MCP if this client has it, else tell the user Node.js is missing. Do not work around a missing prerequisite or a denied write: no installing Node/npm, no private or isolated runtime, no redirected `HOME`.

**Node.js missing, or a write denied (e.g. `EPERM` in a sandbox)?** Never work around it yourself. Relay the exact steps for the user to run in their own terminal — if Node.js is missing, install **22.20+** from [nodejs.org](https://nodejs.org) or their usual package manager (CI: add it to the runner image); then `npm install -g @aisa-one/cli` and `aisa login` — then say *retry*. The CLI and key they install can be reused from here. If they cannot, use MCP or ask which transport they prefer.

Install the official skill first ([Install the Agent Skill](/docs/get-started/agent-skill)): `npx skills add AIsa-team/agent-skills --skill aisa --agent <this harness> --global`. Prefer `--global` unless the user asked for this repo only. Do not use `--all` or `*`. The skill installer requires Node.js **22.20.0+**.

Reuse `@aisa-one/cli` **0.5.0 or later** if present; otherwise install; do not downgrade. Read the on-disk skill. Sign in via that skill and `aisa login --help`. Prove auth with `aisa balance`; `aisa whoami` is local only, and `search` or `schema` may run anonymously, so neither proves auth. `AISA_API_KEY` overrides the stored session; if they conflict, explain both. Never print credentials or send the user to copy a dashboard key. Browser `aisa login` is the primary credential path for interactive use; headless automation uses a pre-provisioned `AISA_API_KEY`.

Workflow: `aisa search` → `aisa schema` when `has_full_schema` is false → `aisa quote` → `aisa call` inside the authorized scope and spend. Take tool names and arguments from search or schema. A missing, failed, or partial quote is not free and is not a batch total or cap. Re-quote if tools, arguments, or scope change. Do not silently retry or expand a batch.

## Direct HTTP fallback

**Gate:** CLI and MCP are both unavailable, HTTP requests are supported, and a valid existing AIsa API key is already available. Read this entire section — endpoint docs, pricing, and the approval XML — before presenting a paid proposal or cost approval, and before any paid request. This path does not bypass invalid credentials, exhausted credit, or an outage of the same API. Do not use a paid request to probe availability. Do not extract or reuse client-owned MCP OAuth tokens.

Use the matching endpoint reference and published pricing: [API Reference](https://aisa.one/docs/api-reference), [Authentication](https://aisa.one/docs/guides/authentication), and [Billing & Credits](https://aisa.one/docs/guides/pricing). Data APIs: `https://api.aisa.one/apis/v1`. Model catalog: `https://api.aisa.one/v1/models`. Before presenting a paid request for approval, read the selected endpoint's full reference or the matching OpenAPI operation, including parameters and charging rules. A catalog, index, or pricing overview is not the endpoint contract.

Send the key as a Bearer token. Success on `/v1/models` or other discovery does not prove authenticated business access. If there is no documented maximum or provider bound, or no auth, stop at that limitation. A changed endpoint, scope, or maximum needs new details and approval.

**API key.** Reuse `AISA_API_KEY`, or an AIsa API key already in this client's authorized secret store. If sources conflict, explain them; do not overwrite a custom key. Browser `aisa login` stores a CLI-managed, auto-refreshing session in `~/.aisa/tokens.json`, not an API key: do not read, copy, or refresh it by hand. Do not use `~/.aisa/key`; it is a legacy mirror that can hold an expired token. If none of those exist and `aisa login` is usable, use the CLI instead of direct HTTP. Otherwise, the last option is for the user to create a key at [console.aisa.one/api-keys](https://console.aisa.one/api-keys) and save it in this client's secret settings or as local `AISA_API_KEY`. Do not ask them to paste the key into chat. Wait for credentials before protected requests. Obtaining a key is not paid-call approval.

### Paid API approval first

This contract applies **only** to direct HTTP calls to paid, dynamically priced, or potentially high-cost data endpoints. It does not apply to documented free discovery. It does not add a separate subsequent-message requirement to ordinary CLI or MCP quote and call.

```xml theme={null}
<IMPORTANT id="paid-api-approval-first">
  <before-paid-data-call>
    Read the matching endpoint documentation and published pricing declaration.
    Docs, /v1/models, and capability or MCP discovery are allowed before approval.
    STOP: a request to collect, research, or report data is not approval. State
    the exact endpoint and scope, formula or rate, and documented maximum USD
    exposure; then wait for a separate user message explicitly approving that
    scope and cap.
    If a provider-controlled dimension has no documented upper bound, do not
    execute: an example or user-stated budget is not an enforceable cap.
  </before-paid-data-call>
  <prohibited>
    Do not run a paid data call in the planning turn, use the initial request as
    consent, or use a paid call to discover price, probe, test, or "just check".
  </prohibited>
  <after-approval>
    Execute only the approved request. If its endpoint, scope, or maximum
    changes, present the new details and obtain new approval.
  </after-approval>
</IMPORTANT>
```

The original task, or an "I approve" in the same planning turn, is not that subsequent approval.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.