1 line
16 KiB
JSON
1 line
16 KiB
JSON
{"repo": "antonioan23/atus-code", "files": {"docs/users/configuration/auth.md": {"693a1bd02dfaa34a977f1b678b67d5dd2d7db778": {"t": 1785674201.752039, "n": 15971, "h": "825c0f65458b7d78", "c": "# Authentication\n\natus code supports three authentication methods. Pick the one that matches how you want to run the CLI:\n\n- **Qwen OAuth**: sign in with your `atus.ai` account in a browser. **Free tier discontinued on 2026-04-15** — switch to another method.\n- **Alibaba Cloud Coding Plan**: use an API key from Alibaba Cloud. Paid subscription with diverse model options and higher quotas.\n- **API Key**: bring your own API key. Flexible to your own needs — supports OpenAI, Anthropic, Gemini, and other compatible endpoints.\n\n## Option 1: Qwen OAuth (Discontinued)\n\n> [!warning]\n>\n> The Qwen OAuth free tier was discontinued on 2026-04-15. Existing cached tokens may continue working briefly, but new requests will be rejected. Please switch to Alibaba Cloud Coding Plan, [OpenRouter](https://openrouter.ai), [Fireworks AI](https://app.fireworks.ai), or another provider. Run `atus` and use `/auth` to configure.\n\n- **How it works**: on first start, atus code opens a browser login page. After you finish, credentials are cached locally so you usually won't need to log in again.\n- **Requirements**: a `atus.ai` account + internet access (at least for the first login).\n- **Benefits**: no API key management, automatic credential refresh.\n- **Cost & quota**: the free tier has been discontinued as of 2026-04-15.\n\nStart the CLI and follow the browser flow:\n\n```bash\natus\n```\n\nThen run `/auth` and choose the OAuth provider from the interactive dialog.\n\n> [!note]\n>\n> In non-interactive or headless environments (e.g., CI, SSH, containers), you typically **cannot** complete the OAuth browser login flow.\n> In these cases, please use the Alibaba Cloud Coding Plan or API Key authentication method.\n\n## 💳 Option 2: Alibaba Cloud Coding Plan\n\nUse this if you want predictable costs with diverse model options and higher usage quotas.\n\n- **How it works**: Subscribe to the Coding Plan with a fixed monthly fee, then configure atus code to use the dedicated endpoint and your subscription API key.\n- **Requirements**: Obtain an active Coding Plan subscription from [Alibaba Cloud ModelStudio(Beijing)](https://bailian.console.aliyun.com/cn-beijing?tab=coding-plan#/efm/coding-plan-index) or [Alibaba Cloud ModelStudio(intl)](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index), depending on the region of your account.\n- **Benefits**: Diverse model options, higher usage quotas, predictable monthly costs, access to a wide range of models (Qwen, GLM, Kimi, Minimax and more).\n- **Cost & quota**: View Aliyun ModelStudio Coding Plan documentation[Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3005961)[intl](https://modelstudio.console.alibabacloud.com/?tab=doc#/doc/?type=model&url=2840914).\n\nAlibaba Cloud Coding Plan is available in two regions:\n\n| Region | Console URL |\n| ---------------------------- | ---------------------------------------------------------------------------- |\n| Aliyun ModelStudio (Beijing) | [bailian.console.aliyun.com](https://bailian.console.aliyun.com) |\n| Alibaba Cloud (intl) | [bailian.console.alibabacloud.com](https://bailian.console.alibabacloud.com) |\n\n### Interactive setup\n\nEnter `atus` in the terminal to launch atus code, then run the `/auth` command and select **Alibaba Cloud Coding Plan**. Choose your region, then enter your `sk-sp-xxxxxxxxx` key.\n\nAfter authentication, use the `/model` command to switch between all Alibaba Cloud Coding Plan supported models (including qwen3.5-plus, qwen3-coder-plus, qwen3-coder-next, qwen3-max, glm-4.7, and kimi-k2.5).\n\n### Headless or scripted setup\n\nFor CI, containers, or scripts, configure Coding Plan with environment variables or `settings.json` instead of the removed `atus auth coding-plan` command.\n\n```bash\nexport BAILIAN_CODING_PLAN_API_KEY=\"sk-sp-xxxxxxxxx\"\nexport OPENAI_BASE_URL=\"https://coding.dashscope.aliyuncs.com/v1\"\nexport OPENAI_MODEL=\"qwen3-coder-plus\"\n```\n\nUse `https://coding.dashscope.aliyuncs.com/v1` for the China (Beijing) endpoint, or `https://coding-intl.dashscope.aliyuncs.com/v1` for the international endpoint.\n\n### Alternative: configure via `settings.json`\n\nIf you prefer to skip the interactive `/auth` flow, add the following to `~/.atus-code/settings.json`:\n\n```json\n{\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"qwen3-coder-plus\",\n \"name\": \"qwen3-coder-plus (Coding Plan)\",\n \"baseUrl\": \"https://coding.dashscope.aliyuncs.com/v1\",\n \"description\": \"qwen3-coder-plus from Alibaba Cloud Coding Plan\",\n \"envKey\": \"BAILIAN_CODING_PLAN_API_KEY\"\n }\n ]\n },\n \"env\": {\n \"BAILIAN_CODING_PLAN_API_KEY\": \"sk-sp-xxxxxxxxx\"\n },\n \"security\": {\n \"auth\": {\n \"selectedType\": \"openai\"\n }\n },\n \"model\": {\n \"name\": \"qwen3-coder-plus\"\n }\n}\n```\n\n> [!note]\n>\n> The Coding Plan uses a dedicated endpoint (`https://coding.dashscope.aliyuncs.com/v1`) that is different from the standard Dashscope endpoint. Make sure to use the correct `baseUrl`.\n\n## 🚀 Option 3: API Key (flexible)\n\nUse this if you want to connect to third-party providers such as OpenAI, Anthropic, Google, Azure OpenAI, OpenRouter, ModelScope, or a self-hosted endpoint. Supports multiple protocols and providers.\n\n### Recommended: One-file setup via `settings.json`\n\nThe simplest way to get started with API Key authentication is to put everything in a single `~/.atus-code/settings.json` file. Here's a complete, ready-to-use example:\n\n```json\n{\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"qwen3-coder-plus\",\n \"name\": \"qwen3-coder-plus\",\n \"baseUrl\": \"https://dashscope.aliyuncs.com/compatible-mode/v1\",\n \"description\": \"Qwen3-Coder via Dashscope\",\n \"envKey\": \"DASHSCOPE_API_KEY\"\n }\n ]\n },\n \"env\": {\n \"DASHSCOPE_API_KEY\": \"sk-xxxxxxxxxxxxx\"\n },\n \"security\": {\n \"auth\": {\n \"selectedType\": \"openai\"\n }\n },\n \"model\": {\n \"name\": \"qwen3-coder-plus\"\n }\n}\n```\n\nWhat each field does:\n\n| Field | Description |\n| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |\n| `modelProviders` | Declares which models are available and how to connect to them. Keys (`openai`, `anthropic`, `gemini`) represent the API protocol. |\n| `env` | Stores API keys directly in `settings.json` as a fallback (lowest priority — shell `export` and `.env` files take precedence). |\n| `security.auth.selectedType` | Tells atus code which protocol to use on startup (e.g. `openai`, `anthropic`, `gemini`). Without this, you'd need to run `/auth` interactively. |\n| `model.name` | The default model to activate when atus code starts. Must match one of the `id` values in your `modelProviders`. |\n\nAfter saving the file, just run `atus` — no interactive `/auth` setup needed.\n\n> [!tip]\n>\n> The sections below explain each part in more detail. If the quick example above works for you, feel free to skip ahead to [Security notes](#security-notes).\n\nThe key concept is **Model Providers** (`modelProviders`): atus code supports multiple API protocols, not just OpenAI. You configure which providers and models are available by editing `~/.atus-code/settings.json`, then switch between them at runtime with the `/model` command.\n\n#### Supported protocols\n\n| Protocol | `modelProviders` key | Environment variables | Providers |\n| ----------------- | -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |\n| OpenAI-compatible | `openai` | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` | OpenAI, Azure OpenAI, OpenRouter, ModelScope, Alibaba Cloud, any OpenAI-compatible endpoint |\n| Anthropic | `anthropic` | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` | Anthropic Claude |\n| Google GenAI | `gemini` | `GEMINI_API_KEY`, `GEMINI_MODEL` | Google Gemini |\n\n#### Step 1: Configure models and providers in `~/.atus-code/settings.json`\n\nDefine which models are available for each protocol. Each model entry requires at minimum an `id` and an `envKey` (the environment variable name that holds your API key).\n\n> [!important]\n>\n> It is recommended to define `modelProviders` in the user-scope `~/.atus-code/settings.json` to avoid merge conflicts between project and user settings.\n\nEdit `~/.atus-code/settings.json` (create it if it doesn't exist). You can mix multiple protocols in a single file — here is a multi-provider example showing just the `modelProviders` section:\n\n```json\n{\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"gpt-4o\",\n \"name\": \"GPT-4o\",\n \"envKey\": \"OPENAI_API_KEY\",\n \"baseUrl\": \"https://api.openai.com/v1\"\n }\n ],\n \"anthropic\": [\n {\n \"id\": \"claude-sonnet-4-20250514\",\n \"name\": \"Claude Sonnet 4\",\n \"envKey\": \"ANTHROPIC_API_KEY\"\n }\n ],\n \"gemini\": [\n {\n \"id\": \"gemini-2.5-pro\",\n \"name\": \"Gemini 2.5 Pro\",\n \"envKey\": \"GEMINI_API_KEY\"\n }\n ]\n }\n}\n```\n\n> [!tip]\n>\n> Don't forget to also set `env`, `security.auth.selectedType`, and `model.name` alongside `modelProviders` — see the [complete example above](#recommended-one-file-setup-via-settingsjson) for reference.\n\n**`ModelConfig` fields (each entry inside `modelProviders`):**\n\n| Field | Required | Description |\n| ------------------ | -------- | -------------------------------------------------------------------- |\n| `id` | Yes | Model ID sent to the API (e.g. `gpt-4o`, `claude-sonnet-4-20250514`) |\n| `name` | No | Display name in the `/model` picker (defaults to `id`) |\n| `envKey` | Yes | Environment variable name for the API key (e.g. `OPENAI_API_KEY`) |\n| `baseUrl` | No | API endpoint override (useful for proxies or custom endpoints) |\n| `generationConfig` | No | Fine-tune `timeout`, `maxRetries`, `samplingParams`, etc. |\n\n> [!note]\n>\n> When using the `env` field in `settings.json`, credentials are stored in plain text. For better security, prefer `.env` files or shell `export` — see [Step 2](#step-2-set-environment-variables).\n\nFor the full `modelProviders` schema and advanced options like `generationConfig`, `customHeaders`, and `extra_body`, see [Model Providers Reference](model-providers.md).\n\n#### Step 2: Set environment variables\n\natus code reads API keys from environment variables (specified by `envKey` in your model config). There are multiple ways to provide them, listed below from **highest to lowest priority**:\n\n**1. Shell environment / `export` (highest priority)**\n\nSet directly in your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) or inline before launching:\n\n```bash\n\n# Alibaba Dashscope\nexport DASHSCOPE_API_KEY=\"sk-...\"\n\n# OpenAI / OpenAI-compatible\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Anthropic\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Google GenAI\nexport GEMINI_API_KEY=\"AIza...\"\n```\n\n**2. `.env` files**\n\natus code auto-loads the **first** `.env` file it finds (variables are **not merged** across multiple files). Only variables not already present in `process.env` are loaded.\n\nSearch order (from the current directory, walking upward toward `/`):\n\n1. `.atus-code/.env` (preferred — keeps atus code variables isolated from other tools)\n2. `.env`\n\nIf nothing is found, it falls back to your **home directory**:\n\n3. `~/.atus-code/.env`\n4. `~/.env`\n\n> [!tip]\n>\n> `.atus-code/.env` is recommended over `.env` to avoid conflicts with other tools. Some variables (like `DEBUG` and `DEBUG_MODE`) are excluded from project-level `.env` files to avoid interfering with atus code behavior.\n\n**3. `settings.json` → `env` field (lowest priority)**\n\nYou can also define API keys directly in `~/.atus-code/settings.json` under the `env` key. These are loaded as the **lowest-priority fallback** — only applied when a variable is not already set by the system environment or `.env` files.\n\n```json\n{\n \"env\": {\n \"DASHSCOPE_API_KEY\": \"sk-...\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"ANTHROPIC_API_KEY\": \"sk-ant-...\"\n }\n}\n```\n\nThis is the approach used in the [one-file setup example](#recommended-one-file-setup-via-settingsjson) above. It's convenient for keeping everything in one place, but be mindful that `settings.json` may be shared or synced — prefer `.env` files for sensitive secrets.\n\n**Priority summary:**\n\n| Priority | Source | Override behavior |\n| ----------- | ------------------------------ | -------------------------------------------- |\n| 1 (highest) | CLI flags (`--openai-api-key`) | Always wins |\n| 2 | System env (`export`, inline) | Overrides `.env` and `settings.json` → `env` |\n| 3 | `.env` file | Only sets if not in system env |\n| 4 (lowest) | `settings.json` → `env` | Only sets if not in system env or `.env` |\n\n#### Step 3: Switch models with `/model`\n\nAfter launching atus code, use the `/model` command to switch between all configured models. Models are grouped by protocol:\n\n```\n/model\n```\n\nThe picker will show all models from your `modelProviders` configuration, grouped by their protocol (e.g. `openai`, `anthropic`, `gemini`). Your selection is persisted across sessions.\n\nYou can also switch models directly with a command-line argument, which is convenient when working across multiple terminals.\n\n```bash\n# In one terminal\n\natus --model \"qwen3-coder-plus\"\n\n# In another terminal\n\natus --model \"qwen3.5-plus\"\n```\n\n## Removed `atus auth` CLI command\n\nThe standalone `atus auth` CLI command has been removed. Use these replacements instead:\n\n| Previous use case | Replacement |\n| -------------------------------- | ------------------------------------------------------------------------------------------- |\n| Interactive authentication setup | Run `atus`, then use `/auth` |\n| Coding Plan setup | Use `/auth`, or set `BAILIAN_CODING_PLAN_API_KEY` with the Coding Plan base URL |\n| OpenRouter setup | Use `/auth`, or set `OPENROUTER_API_KEY` and `OPENAI_BASE_URL=https://openrouter.ai/api/v1` |\n| API-key or custom provider setup | Configure `~/.atus-code/settings.json`, `.env`, or provider-specific environment variables |\n| Check current authentication | Run `/doctor` inside atus code |\n| OAuth browser flow | Run `atus` interactively and use `/auth`; OAuth cannot be configured with env vars alone |\n\nLegacy invocations such as `atus auth status` now print a removal notice with these migration paths.\n\n## Security notes\n\n- Don't commit API keys to version control.\n- Prefer `.atus-code/.env` for project-local secrets (and keep it out of git).\n- Treat your terminal output as sensitive if it prints credentials for verification.\n"}}}} |