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.

1. Install

   npm install -g @aisa-one/cli
   aisa --version
   

   Requires Node.js 18 or later.

2. Sign in

   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.

3. Ask your agent

   Paste this into the coding agent that runs in this terminal:

   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.
   

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	Free

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 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): 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, Authentication, and Billing & Credits. 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 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.

<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.