@aisa-one/cli 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -7,11 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.5.0] — Unreleased
+## [0.5.2] — 2026-09-10
 
-PR21 command-surface cleanup. Distinct from the unpublished `0.4.0` main
-baseline (registry latest remains `0.3.0`; `0.4.0` was never tagged or
-published).
+Compatible patch on published `0.5.1`. Expanded `aisa login --help` for Agent
+sign-in handoff, plus a default-off login-help evaluation. No auth runtime,
+credential-precedence, or command-surface changes.
+
+### Changed
+
+- `aisa login --help` owns accessible-browser vs persistent headless TTY, live
+  URL relay, one-time paste into the same living process, reuse of a running
+  login, stale-session recovery, no-TTY native MCP OAuth, and connected-only
+  after a successful balance check.
+
+### Added
+
+- Default-off `eval/agent-quickstart/login-handoff/`. Excluded from the npm
+  package; does not run in default CI or against production AIsa credentials.
+
+## [0.5.1] — 2026-09-10
+
+Compatible patch on published `0.5.0`. Browser-login-first onboarding
+guidance and an opt-in Quickstart Skill evaluation. No new commands, auth
+mechanisms, or credential-precedence changes.
+
+### Changed
+
+- README, missing-key errors, `whoami`, and Router help recommend `aisa login`
+  (browser; stores a CLI key) before pasting a key. `AISA_API_KEY` and
+  `aisa login --key` remain for CI. Resolution order is unchanged:
+  `AISA_API_KEY`, then `~/.aisa/key`, then legacy login.
+- Quick Start covers login, discovery, catalog browse, and quote. It does not
+  copy `aisa chat` or `aisa call`. Quote is a price observation; approval and
+  whether to execute remain caller-owned guidance, not an enforced CLI gate.
+
+### Added
+
+- Default-off `eval/agent-quickstart/` Skill ablation. Reuses the existing
+  Router stub and pack path. Excluded from the npm package; does not run in
+  default CI or against production AIsa credentials.
+
+## [0.5.0] — 2026-09-09
+
+PR21 command-surface cleanup. Published to npm as `0.5.0`. Distinct from the
+unpublished `0.4.0` main baseline (`0.4.0` was never tagged or published).
 
 ### Breaking
 
@@ -41,7 +80,7 @@ published).
 ## [0.4.0] — unpublished main baseline
 
 Unpublished `main` candidate as of 2026-09-08. Not tagged and not on npm
-(registry latest remains `0.3.0`). Kept so the Router work and the
+(skipped between `0.3.0` and published `0.5.0`). Kept so the Router work and the
 `api search` / `api show` / `run` deprecation history stay identifiable.
 
 ### Breaking
@@ -385,7 +424,9 @@ supports today; nothing here depends on a backend change.
 - Config commands (`aisa config get|set|list|reset`) and auth
   (`aisa login|logout|whoami`).
 
-[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/AIsa-team/cli/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/AIsa-team/cli/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/AIsa-team/cli/compare/v0.3.0...v0.5.0
 [0.4.0]: https://github.com/AIsa-team/cli/compare/v0.3.0...b5c0b04b2a7a2cb9efcb568be5ee5440d7f7d94d
 [0.3.0]: https://github.com/AIsa-team/cli/compare/v0.2.4...v0.3.0

package/README.md

@@ -14,8 +14,8 @@ npm install -g @aisa-one/cli
 ## Quick Start
 
 ```bash
-# Authenticate (or set AISA_API_KEY)
-aisa login --key sk-your-api-key
+# Sign in (browser; stores a CLI key — no key to copy)
+aisa login
 
 # Discover published tools (Router; search/schema may be anonymous)
 aisa search "company facts" --json
@@ -25,17 +25,19 @@ aisa schema get_financial_company_facts --json
 aisa api list
 aisa api show financial
 
-# Chat with any model
-aisa chat "Explain quantum computing" --model claude-opus-4-6
-
-# Quote then execute a published Router tool (same request JSON)
+# Quote a published Router tool (does not execute)
 aisa quote --input '{"calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --json
-aisa call --input '{"calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --json
 ```
 
-Get your API key at
-[console.aisa.one/api-keys](https://console.aisa.one/api-keys). New accounts
-receive $5 in free credits.
+`aisa login` opens a browser, signs you in, and stores a CLI key. You do not
+need to create or paste a key from the console. For CI or scripts, set
+`AISA_API_KEY` or run `aisa login --key <key>`. New accounts receive $5 in
+free credits.
+
+This first block does not run `aisa chat` or `aisa call`. Quote is a price
+observation, not authorization to execute. See
+[Published tools](#published-tools-tool-router) for the quote/approval
+contract before a billable call.
 
 Root help lists 21 explicit commands plus implicit `help`. Removed domain
 shortcuts and raw execution names are unknown commands — not aliases and
@@ -102,8 +104,10 @@ HTTP error; `3` means the Router returned a batch with at least one failed
 item.
 
 `search` and `schema` may be anonymous. `quote` and `call` require a
-configured AIsa API key: `AISA_API_KEY`, then `~/.aisa/key`, then legacy
-login. `aisa login` and `AISA_API_KEY` are alternatives. The default Router
+configured AIsa API key. Sign in with `aisa login` first; it mints and stores
+a CLI key. Resolution order is unchanged: `AISA_API_KEY`, then `~/.aisa/key`,
+then legacy login. `AISA_API_KEY` still takes precedence over the stored key.
+For CI, set `AISA_API_KEY` or use `aisa login --key <key>`. The default Router
 origin is `https://tools.aisa.one` (independent of `baseUrl` /
 `https://api.aisa.one`). Point a test Router at `AISA_ROUTER_BASE_URL` (origin
 or prefix before `/v1/tool-router/...`), or `aisa config set routerUrl`. There
@@ -319,7 +323,8 @@ Settings:
   independent of `baseUrl`); overridden by `AISA_ROUTER_BASE_URL`
 - `outputFormat` — `text` or `json`
 
-Environment variables: `AISA_API_KEY` takes precedence over the stored key.
+`aisa login` stores a CLI key in `~/.aisa/key`. Environment variables:
+`AISA_API_KEY` takes precedence over the stored key.
 `AISA_ROUTER_BASE_URL` is the Router origin/prefix before
 `/v1/tool-router/...` and overrides the default `https://tools.aisa.one`.
 `AISA_CACHE_DIR` relocates the cache. `GITHUB_TOKEN`

package/dist/commands/auth.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { setApiKey, clearApiKey, getApiKey, getKeySource, maskKey } from "../config.js";
+import { setApiKey, clearApiKey, getApiKey, getKeySource, maskKey, AUTH_SETUP_GUIDANCE } from "../config.js";
 import { success, info } from "../utils/display.js";
 import { CONSOLE_URL, ENV_VAR_NAME } from "../constants.js";
 export async function loginAction(options) {
@@ -55,7 +55,7 @@ export function whoamiAction() {
     const source = getKeySource();
     if (!key) {
         info("Not authenticated.");
-        console.log(chalk.gray(`  Run "aisa login --key <key>" or set ${ENV_VAR_NAME}`));
+        console.log(chalk.gray(`  ${AUTH_SETUP_GUIDANCE}`));
         return;
     }
     console.log(`  Key:    ${maskKey(key)}`);

package/dist/commands/oauth-login.d.ts

@@ -27,6 +27,8 @@ export declare function mintCliKey(options?: {
     lang?: Lang;
     catcher?: OAuthCatcher;
 }): Promise<string>;
+/** Commander after-help for `aisa login`. Mechanics only; runtime is unchanged. */
+export declare function loginHelpAfter(): string;
 export declare function oauthLogin(options?: {
     open?: boolean;
     lang?: Lang;

package/dist/commands/oauth-login.js

@@ -319,6 +319,20 @@ export async function mintCliKey(options = {}) {
     setApiKey(minted.key);
     return minted.key;
 }
+/** Commander after-help for `aisa login`. Mechanics only; runtime is unchanged. */
+export function loginHelpAfter() {
+    return `
+Default: open a browser this person can actually use (SSH/CI/no display skip the local open). The live authorize URL is printed at the same time — relay that exact URL immediately. Do not invent, shorten, or delay it.
+
+--no-browser needs a persistent interactive TTY. Agents request only the one-time redirect URL or code — never an API key, access token, or refresh token. Paste that result into this same living process once. Reuse a running login; do not start another. "Done" is not that input. If they cannot type here, relay the paste through chat into this PTY. An empty line cancels.
+
+If this process already timed out, or the URL/code is from an older run, start a fresh aisa login and use the new URL and its result. Do not reuse a stale paste.
+
+No browser and no TTY: this CLI cannot complete OAuth here. Normal setup is native MCP OAuth at https://tools.aisa.one/mcp.
+
+Do not report connected unless login stored a key and the following balance check succeeded. aisa whoami and a stored local key are not proof. Scripts/CI: AISA_API_KEY or --key.
+`;
+}
 export async function oauthLogin(options = {}) {
     if (options.open === false && !process.stdin.isTTY) {
         error("--no-browser needs an interactive terminal to paste the redirect URL into.");

package/dist/commands/tool-help.js

@@ -32,7 +32,7 @@ export const ROUTER_EXITS = {
 const FLOW = "Recommended sequence: aisa search → aisa schema when has_full_schema=false → aisa quote → aisa call.";
 const INLINE = "--input is inline JSON text (no file required). Shell examples are POSIX sh with single-quoted --input; apostrophes are written as '\\'' so $(), backticks, and other expansions stay literal. -f FILE and -f - remain available.";
 const JSON_CONTRACT = "--json writes the unmodified application body, including MCP identifiers and numeric tokens. Human output maps only AISA_SEARCH_TOOL, AISA_BATCH_GET_SCHEMA, AISA_BATCH_QUOTE, and AISA_BATCH_USE to aisa search / schema / quote / call.";
-const KEY_RESOLUTION = "AISA_API_KEY, then ~/.aisa/key, then legacy login. aisa login and AISA_API_KEY are alternatives.";
+const KEY_RESOLUTION = "Prefer aisa login (stores a CLI key). Resolution: AISA_API_KEY, then ~/.aisa/key, then legacy login. CI: AISA_API_KEY or aisa login --key.";
 const ENFORCED_OPTIONAL = `Enforced: invalid local input exits 2 and is not sent. A configured AIsa API key is optional (${KEY_RESOLUTION}).`;
 const ENFORCED_REQUIRED = `Enforced: quote and call refuse to run without a configured AIsa API key (${KEY_RESOLUTION}). Invalid local input exits 2 and is not sent. search and schema may be anonymous.`;
 const NOT_ENFORCED = "Not enforced: the CLI does not record quotes, approvals, or budget caps and does not reject an unquoted aisa call.";

package/dist/commands/tools.js

@@ -1,7 +1,6 @@
 import ora from "ora";
 import chalk from "chalk";
-import { getApiKey } from "../config.js";
-import { ENV_VAR_NAME } from "../constants.js";
+import { getApiKey, MISSING_API_KEY_GUIDANCE } from "../config.js";
 import { CliError, EXIT_PARTIAL, EXIT_TRANSPORT, transportError } from "../cli-error.js";
 import { routerPost } from "../router.js";
 import { error as printError } from "../utils/display.js";
@@ -61,7 +60,7 @@ async function runToolCommand(kind, operands, options, auth) {
 function requireRouterKey(kind) {
     const key = getApiKey();
     if (!key) {
-        throw new CliError(`No API key found. Run "aisa login --key <key>" or set ${ENV_VAR_NAME}. ` +
+        throw new CliError(`${MISSING_API_KEY_GUIDANCE} ` +
             `search and schema may be anonymous; ${kind} will not run without a key. ` +
             `Do not invent a business result.`, EXIT_TRANSPORT);
     }

package/dist/config.d.ts

@@ -1,4 +1,7 @@
 export declare function getApiKey(): string | undefined;
+/** Next step when no local credential is present. Browser login first; env/--key are CI. */
+export declare const AUTH_SETUP_GUIDANCE = "Run \"aisa login\". For CI, set AISA_API_KEY or use \"aisa login --key <key>\".";
+export declare const MISSING_API_KEY_GUIDANCE = "No API key found. Run \"aisa login\". For CI, set AISA_API_KEY or use \"aisa login --key <key>\".";
 export declare function requireApiKey(): string;
 export declare function setApiKey(key: string): void;
 export declare function clearApiKey(): void;

package/dist/config.js

@@ -84,10 +84,13 @@ export function getApiKey() {
     }
     return undefined;
 }
+/** Next step when no local credential is present. Browser login first; env/--key are CI. */
+export const AUTH_SETUP_GUIDANCE = `Run "aisa login". For CI, set ${ENV_VAR_NAME} or use "aisa login --key <key>".`;
+export const MISSING_API_KEY_GUIDANCE = `No API key found. ${AUTH_SETUP_GUIDANCE}`;
 export function requireApiKey() {
     const key = getApiKey();
     if (!key) {
-        console.error(`No API key found. Run "aisa login --key <key>" or set ${ENV_VAR_NAME}.`);
+        console.error(MISSING_API_KEY_GUIDANCE);
         process.exit(1);
     }
     return key;

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.5.2";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */
 export declare const BASE_URL = "https://api.aisa.one";
 export declare const ENV_VAR_NAME = "AISA_API_KEY";

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = "0.5.0";
+export const VERSION = "0.5.2";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */
 export const BASE_URL = "https://api.aisa.one";
 export const ENV_VAR_NAME = "AISA_API_KEY";

package/dist/index.js

@@ -4,6 +4,7 @@ import { VERSION } from "./constants.js";
 import { CliError } from "./cli-error.js";
 // Auth
 import { loginAction, logoutAction, whoamiAction } from "./commands/auth.js";
+import { loginHelpAfter } from "./commands/oauth-login.js";
 // Account
 import { balanceAction, topupAction, usageAction } from "./commands/account.js";
 // API
@@ -75,6 +76,7 @@ program
     .description("Sign in to AIsa — browser sign-in by default, or --key to paste one")
     .option("--key <key>", "API key (skips the browser sign-in)")
     .option("--no-browser", "Print the sign-in URL and paste the redirect back (detected on its own over SSH)")
+    .addHelpText("after", loginHelpAfter())
     .action(wrap(loginAction));
 program
     .command("logout")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisa-one/cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "CLI for the AIsa unified AI infrastructure platform - one API key for 80+ LLMs and 900+ endpoints across finance, search, social, and video APIs",
   "type": "module",
   "main": "dist/index.js",