@jiayunxie/aerial 0.1.4 → 0.1.5

package/README.md

@@ -25,9 +25,8 @@ aerial login
 aerial key generate
 aerial key print
 aerial start
-aerial setup codex
-aerial setup claude --model <available-copilot-model-id>
-aerial setup all
+aerial setup codex [--model <responses-model-id>]
+aerial setup claude [--model <messages-model-id>]
 aerial setup status
 aerial setup restore <codex|claude|all> --latest
 aerial service install
@@ -85,10 +84,12 @@ node src/cli.js --help
 
 ## First Run
 
-Configure your local clients. This also creates Aerial's local API key and wires it into supported clients:
+Configure the local client you use. These commands also create Aerial's local API key and wire it into the selected client:
 
 ```bash
-aerial setup all --model <available-copilot-model-id>
+aerial setup codex
+# optional, if you use Claude Code too:
+aerial setup claude
 ```
 
 If Codex or Claude Code was already open, restart it after setup so it rereads the updated client config.
@@ -99,10 +100,10 @@ Log in to GitHub with device flow:
 aerial login
 ```
 
-Start the local server:
+Install and start the background service:
 
 ```bash
-aerial start
+aerial service install
 ```
 
 Check health:
@@ -116,7 +117,7 @@ curl http://127.0.0.1:18181/health
 Aerial configures Codex through the Responses wire API provider path:
 
 ```bash
-aerial setup codex --model <available-copilot-model-id>
+aerial setup codex
 ```
 
 This updates `~/.codex/config.toml` and creates a timestamped backup first. If you only want to inspect the exact change, set `HOME`/`USERPROFILE` to a temporary directory before running setup. The inserted provider uses:
@@ -158,6 +159,8 @@ This updates `~/.claude/settings.json` and creates a timestamped backup first. I
 
 The `model` field is written when you pass `--model` or set Aerial's `defaultModel`; otherwise Aerial leaves any existing Claude Code model choice alone while still switching the gateway to the local Aerial endpoint.
 
+If you need explicit models, pass `--model <responses-model-id>` to `aerial setup codex` and `--model <messages-model-id>` to `aerial setup claude`. Aerial intentionally does not provide `aerial setup all` as a setup shortcut because Codex and Claude Code may need different model IDs.
+
 `aerial key print` prints the locally stored Aerial API key for Claude Code's helper flow. Users normally do not need to call it directly.
 
 When switching from another Anthropic-compatible gateway, setup removes stale `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`, and `ANTHROPIC_DEFAULT_*_MODEL` entries from Claude Code's managed `env` block so `apiKeyHelper` and the Aerial gateway are the active route.
@@ -186,7 +189,7 @@ Aerial is for personal local use only.
 - Copilot inference routes are an observed compatibility target, not a public stable GitHub REST API.
 - `/v1/messages/count_tokens` is a local estimate, not upstream tokenization.
 - Bundled service management is implemented for macOS (launchd) and Windows (Task Scheduler). On Linux, run `aerial start` directly or wrap it in your own init system.
-- Model choice is not automated; query `/v1/models` and select an available model explicitly.
+- For explicit model overrides, query `/v1/models`, choose a `responses` model for Codex and a `messages` model for Claude Code, then rerun the client-specific setup command with `--model`.
 - Chat Completions requests normalize `max_tokens` to `max_completion_tokens` for newer OpenAI models that reject the older field.
 - Prompt caching is upstream-managed: Aerial does not store prompt bodies locally, and it preserves or injects cache protocol fields before forwarding.
 

package/docs/usage.md

@@ -23,10 +23,12 @@ node src/cli.js --help
 ## 2. Configure Local Clients
 
 ```bash
-aerial setup all --model <model-id>
+aerial setup codex
+# optional, if you use Claude Code too:
+aerial setup claude
 ```
 
-Aerial creates a local API key, stores it privately, and configures supported clients to use it. If Codex or Claude Code was already open, restart it after setup so it rereads the updated client config.
+Aerial creates a local API key, stores it privately, and configures the selected clients to use it. There is intentionally no `aerial setup all` setup shortcut: Codex and Claude Code can need different model IDs, so setup stays client-specific. If Codex or Claude Code was already open, restart it after setup so it rereads the updated client config.
 
 ## 3. Login To GitHub
 
@@ -39,15 +41,15 @@ Open the printed URL, enter the user code, and authorize the GitHub OAuth device
 ## 4. Start Server
 
 ```bash
-aerial start
+aerial service install
 ```
 
-Default URL: `http://127.0.0.1:18181`.
+Default URL: `http://127.0.0.1:18181`. `aerial service install` is the daily-use path on macOS and Windows because it installs and starts the local background service. Use `aerial start` only when you want a foreground debug process in the current terminal.
 
 ## 5. Configure Codex CLI
 
 ```bash
-aerial setup codex --model <model-id>
+aerial setup codex
 ```
 
 The setup command backs up and merges `~/.codex/config.toml`, then configures Codex to fetch the local Aerial key through a command-backed provider auth helper:
@@ -68,10 +70,12 @@ The local key is generated and stored by Aerial automatically. Users do not need
 
 For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
 
+If you need to pin a model, first run `aerial probe` or call `/v1/models`, choose a model whose Aerial routes include `responses`, then run `aerial setup codex --model <responses-model-id>`.
+
 ## 6. Configure Claude Code
 
 ```bash
-aerial setup claude --model <model-id>
+aerial setup claude
 ```
 
 The setup command backs up and merges `~/.claude/settings.json`, using `apiKeyHelper = "aerial key print"` and `ANTHROPIC_BASE_URL=http://127.0.0.1:18181`. When you pass `--model` or set Aerial's `defaultModel`, it also writes Claude Code's default `model` to that Aerial-routed model.
@@ -80,6 +84,8 @@ If Claude Code was previously pointed at another Anthropic-compatible gateway, s
 
 For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
 
+If you need to pin a model, first run `aerial probe` or call `/v1/models`, choose a model whose Aerial routes include `messages`, then run `aerial setup claude --model <messages-model-id>`.
+
 ## 7. Verify
 
 ```bash
@@ -314,7 +320,7 @@ Best practice: put stable system/project/tool context first, put changing user i
 ## Troubleshooting
 
 - `503 Missing GitHub token`: run `aerial login`.
-- `401 Invalid or missing Aerial API key`: run `aerial setup all`, then restart the client terminal or VS Code.
+- `401 Invalid or missing Aerial API key`: run `aerial setup codex` or `aerial setup claude` for the client you use, then restart the client terminal or VS Code.
 - Claude Code cannot read key: ensure `aerial` is on `PATH`; it uses `aerial key print` as its helper.
 - Upstream compatibility error: run `aerial doctor`, then retry with a model returned by `/v1/models`.
 - `Unsupported parameter: max_tokens`: Aerial normalizes Chat Completions `max_tokens` into `max_completion_tokens` before forwarding to newer OpenAI models.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiayunxie/aerial",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Local-only GitHub Copilot proxy for Codex CLI and Claude Code.",
   "type": "module",
   "private": false,

package/src/cli.js

@@ -31,7 +31,6 @@ Usage:
   aerial start [--host 127.0.0.1] [--port 18181]
   aerial setup codex [--model <id>]
   aerial setup claude [--model <id>]
-  aerial setup all [--model <id>]
   aerial setup status [--json]
   aerial setup restore <codex|claude|all> --latest
   aerial service install
@@ -117,14 +116,7 @@ async function main() {
       return;
     }
     if (subcommand === "all") {
-      const model = argValue(rest, "--model");
-      const codex = setupCodex({ model, authCommand: codexAuthCommand() });
-      const claude = setupClaude({ model });
-      console.log(`Updated Codex config: ${codex.file}`);
-      console.log("Configured Codex to read the local Aerial key automatically.");
-      console.log(`Updated Claude settings: ${claude.file}`);
-      if (claude.model) console.log(`Configured Claude default model: ${claude.model}`);
-      return;
+      throw new Error("aerial setup all has been removed. Run `aerial setup codex` and/or `aerial setup claude` instead.");
     }
     if (subcommand === "status") {
       const status = setupStatus();

package/src/doctor.js

@@ -6,7 +6,7 @@ export function doctor() {
   const config = loadConfig();
   const checks = [
     { name: "config", ok: fs.existsSync(configPath()), detail: configPath() },
-    { name: "api_key", ok: Boolean(config.apiKeyHash), detail: fs.existsSync(apiKeyPath()) ? apiKeyPath() : config.apiKeyHash ? "hash configured" : "run: aerial setup all" },
+    { name: "api_key", ok: Boolean(config.apiKeyHash), detail: fs.existsSync(apiKeyPath()) ? apiKeyPath() : config.apiKeyHash ? "hash configured" : "run: aerial setup codex or aerial setup claude" },
     { name: "github_token", ok: fs.existsSync(githubTokenPath()) || Boolean(process.env.AERIAL_GITHUB_TOKEN), detail: fs.existsSync(githubTokenPath()) ? githubTokenPath() : "run: aerial login" },
     { name: "node", ok: Number(process.versions.node.split(".")[0]) >= 22, detail: process.version },
     { name: "bind", ok: config.host === "127.0.0.1", detail: `${config.host}:${config.port}` }