zai-cli 0.1.3__tar.gz → 0.1.7__tar.gz

{zai_cli-0.1.3 → zai_cli-0.1.7}/CHANGELOG.md

@@ -5,6 +5,68 @@ All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project uses [Semantic Versioning](https://semver.org/).
 
+## [0.1.7] - 2026-06-28
+
+### Changed
+
+- Changed first-run interactive onboarding so `zai` offers provider login inside
+  the interactive startup flow instead of sending users back to an external
+  command.
+
+## [0.1.6] - 2026-06-28
+
+### Added
+
+- Added `zai auth status`, `zai auth login <provider>`,
+  `zai auth logout <provider>`, and `zai auth doctor`.
+- Added interactive `/auth status`, `/auth login <provider>`,
+  `/auth logout <provider>`, and `/auth doctor`.
+- Added a provider authentication registry covering Gemini, Groq, OpenAI,
+  Anthropic, OpenRouter, Cerebras, Qwen, and Ollama.
+- Added safe external Codex and Claude CLI detection/login prompts without
+  reading or copying private token contents.
+
+### Changed
+
+- Routed setup key saving through the shared auth helper.
+- Documented API-key versus external account-login boundaries.
+
+## [0.1.5] - 2026-06-26
+
+### Added
+
+- Added project-scoped memory stored in `.zai/project_memory.json`.
+- Added `zai memory project`, `zai memory refresh`,
+  `zai memory remember <fact>`, and `zai memory forget <fact-or-id>`.
+- Added interactive `/memory project`, `/memory refresh`, `/remember <fact>`,
+  and `/forget <fact-or-id>`.
+- Added automatic project detection for common Python, Node/Next.js, Go, and
+  Rust project files.
+
+### Changed
+
+- Interactive mode now loads existing project memory into pinned context.
+- Project memory stores summaries and explicit facts only, avoiding secrets,
+  `.env` contents, tokens, passwords, and full source files.
+
+## [0.1.4] - 2026-06-26
+
+### Added
+
+- Added a shared first-run setup wizard for both `zai setup` and interactive
+  `/setup`.
+- Added `zai doctor` for install, key, model, and provider diagnostics.
+- Added optional provider validation from setup with a user-approved tiny test
+  request.
+- Added `/exit` and `/quit` in interactive mode.
+
+### Changed
+
+- Reworked `/help` into a short beginner-focused guide.
+- Reworked `/commands` into grouped setup, project, session, model, and
+  advanced command sections.
+- Expanded first-time user README guidance and troubleshooting.
+
 ## [0.1.3] - 2026-06-24
 
 ### Fixed

{zai_cli-0.1.3/zai_cli.egg-info → zai_cli-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.1.3
+Version: 0.1.7
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -74,12 +74,146 @@ plugins and MCP servers.
 
 ```bash
 pip install zai-cli
-zai setup
 ```
 
 The PyPI distribution is named `zai-cli`; the installed command and Python
 package remain `zai`.
 
+## Start in 60 seconds
+
+```bash
+python -m pip install --upgrade --no-cache-dir zai-cli
+zai
+```
+
+If no provider key is configured, `zai` will offer setup immediately. Follow the
+prompt, choose a provider, paste your own API key, then start working in the
+same terminal.
+
+## First run
+
+Run `zai` inside the folder you want to work on:
+
+```bash
+cd path/to/project
+zai
+```
+
+Useful first commands inside interactive mode:
+
+```text
+/              Show commands
+/setup         Configure or update provider keys
+/model         Show available models
+/review        Review current changes
+/exit          Leave zai
+```
+
+You can also type normally, for example:
+
+```text
+explain this project
+find bugs in the auth code
+create a README for this folder
+```
+
+## Recommended free providers
+
+Users must use their own API keys. Do not share your personal key.
+
+- Gemini: free starting point for general use,
+  <https://aistudio.google.com/app/apikey>
+- Groq: free and fast, <https://console.groq.com/keys>
+- OpenAI: paid, <https://platform.openai.com/api-keys>
+
+Keys are saved locally in `~/.zai/.env`. You can inspect current status with:
+
+```bash
+zai doctor
+zai model list
+```
+
+## Authentication
+
+`zai` uses provider API keys for its own model calls. Account login for external
+tools such as Codex or Claude Code is separate.
+
+Check what is connected:
+
+```bash
+zai auth status
+zai auth doctor
+```
+
+Connect a provider API key:
+
+```bash
+zai auth login gemini
+zai auth login groq
+zai auth login openai
+zai auth login anthropic
+```
+
+Remove a saved API key from `zai`:
+
+```bash
+zai auth logout groq
+```
+
+Credential boundaries:
+
+- `zai` stores provider API keys in `~/.zai/.env` by default.
+- `zai` never prints raw keys.
+- Do not paste API keys into normal chat prompts, issues, tickets, or logs.
+- `zai` does not copy Codex or Claude private token files.
+- If `codex` or `claude` is installed, `zai auth login openai` or
+  `zai auth login anthropic` can offer to run the official external CLI login,
+  after asking for confirmation.
+- OpenAI/Anthropic API keys power `zai`; ChatGPT/Codex or Claude account login
+  powers those official external CLIs.
+
+## Troubleshooting
+
+If `zai` still shows an older version:
+
+```bash
+python -m pip install --upgrade --force-reinstall --no-cache-dir zai-cli
+zai --version
+```
+
+If the `zai` command is not found:
+
+```bash
+python -m zai --version
+python -m pip show zai-cli
+```
+
+If no provider is available:
+
+```bash
+zai doctor
+zai auth status
+zai setup
+```
+
+If a key is invalid or missing:
+
+```bash
+zai auth login groq
+zai model test groq
+```
+
+If external Codex or Claude login fails, use their official CLI directly:
+
+```bash
+codex login
+codex login --device-auth
+claude login
+```
+
+If `codex` or `claude` is not found, install the official CLI first or use a
+provider API key with `zai auth login <provider>`.
+
 For local development:
 
 ```bash
@@ -132,10 +266,51 @@ starting points; OpenAI is paid. Keys are saved locally in `~/.zai/.env`.
 Inside interactive mode, type `/` and press Tab to see slash commands, or run
 `/help` and `/commands`.
 
+## Project memory
+
+`zai` can keep small project-specific memory in the folder you run it from:
+
+```text
+.zai/project_memory.json
+```
+
+This is separate from conversation session history. It stores a compact summary
+of project signals such as languages, frameworks, important files, common setup,
+test, and run commands, plus facts you explicitly ask `zai` to remember. It does
+not store API keys, `.env` contents, tokens, passwords, or full source files.
+
+Create or refresh memory:
+
+```bash
+zai memory refresh
+zai memory project
+```
+
+Inside interactive mode:
+
+```text
+/memory project       Show project memory
+/memory refresh       Refresh detected project summary
+/remember <fact>      Save a project fact
+/forget <fact-or-id>  Delete a saved fact
+```
+
+When `zai` starts in a folder that already has `.zai/project_memory.json`, it
+loads a short pinned summary so future answers can use that folder's context.
+Different folders keep different memories.
+
+Memory types:
+
+- Session history: previous conversation messages saved globally under `~/.zai`.
+- Project memory: small per-folder facts in `.zai/project_memory.json`.
+- Repo map: generated structure summary used for repository questions; it is not
+  long-term memory.
+
 ## Main commands
 
 ```text
 zai                         Start the interactive project assistant
+zai doctor                  Check install, keys, and provider readiness
 zai commands                List interactive slash commands
 zai ask <message>           Send a one-off message
 zai chat [message]          Chat with the configured model
@@ -169,8 +344,16 @@ zai model remove <name>     Remove a custom model alias
 zai model configure <name>  Set timeout and retry policy
 zai model info <name>       Show effective model configuration
 zai model test <name>       Verify credentials and model availability
+zai auth status             Show API-key and external CLI auth status
+zai auth login <provider>   Connect a provider API key
+zai auth logout <provider>  Remove a provider API key from zai
+zai auth doctor             Show auth troubleshooting guidance
 zai memory show             Show last task metadata
 zai memory projects         List remembered projects
+zai memory project          Show project-scoped memory
+zai memory refresh          Create or refresh project-scoped memory
+zai memory remember <fact>  Save a project fact
+zai memory forget <id/text> Delete a project fact
 zai memory clear            Clear memory metadata
 
 zai hook list

{zai_cli-0.1.3 → zai_cli-0.1.7}/README.md

@@ -17,12 +17,146 @@ plugins and MCP servers.
 
 ```bash
 pip install zai-cli
-zai setup
 ```
 
 The PyPI distribution is named `zai-cli`; the installed command and Python
 package remain `zai`.
 
+## Start in 60 seconds
+
+```bash
+python -m pip install --upgrade --no-cache-dir zai-cli
+zai
+```
+
+If no provider key is configured, `zai` will offer setup immediately. Follow the
+prompt, choose a provider, paste your own API key, then start working in the
+same terminal.
+
+## First run
+
+Run `zai` inside the folder you want to work on:
+
+```bash
+cd path/to/project
+zai
+```
+
+Useful first commands inside interactive mode:
+
+```text
+/              Show commands
+/setup         Configure or update provider keys
+/model         Show available models
+/review        Review current changes
+/exit          Leave zai
+```
+
+You can also type normally, for example:
+
+```text
+explain this project
+find bugs in the auth code
+create a README for this folder
+```
+
+## Recommended free providers
+
+Users must use their own API keys. Do not share your personal key.
+
+- Gemini: free starting point for general use,
+  <https://aistudio.google.com/app/apikey>
+- Groq: free and fast, <https://console.groq.com/keys>
+- OpenAI: paid, <https://platform.openai.com/api-keys>
+
+Keys are saved locally in `~/.zai/.env`. You can inspect current status with:
+
+```bash
+zai doctor
+zai model list
+```
+
+## Authentication
+
+`zai` uses provider API keys for its own model calls. Account login for external
+tools such as Codex or Claude Code is separate.
+
+Check what is connected:
+
+```bash
+zai auth status
+zai auth doctor
+```
+
+Connect a provider API key:
+
+```bash
+zai auth login gemini
+zai auth login groq
+zai auth login openai
+zai auth login anthropic
+```
+
+Remove a saved API key from `zai`:
+
+```bash
+zai auth logout groq
+```
+
+Credential boundaries:
+
+- `zai` stores provider API keys in `~/.zai/.env` by default.
+- `zai` never prints raw keys.
+- Do not paste API keys into normal chat prompts, issues, tickets, or logs.
+- `zai` does not copy Codex or Claude private token files.
+- If `codex` or `claude` is installed, `zai auth login openai` or
+  `zai auth login anthropic` can offer to run the official external CLI login,
+  after asking for confirmation.
+- OpenAI/Anthropic API keys power `zai`; ChatGPT/Codex or Claude account login
+  powers those official external CLIs.
+
+## Troubleshooting
+
+If `zai` still shows an older version:
+
+```bash
+python -m pip install --upgrade --force-reinstall --no-cache-dir zai-cli
+zai --version
+```
+
+If the `zai` command is not found:
+
+```bash
+python -m zai --version
+python -m pip show zai-cli
+```
+
+If no provider is available:
+
+```bash
+zai doctor
+zai auth status
+zai setup
+```
+
+If a key is invalid or missing:
+
+```bash
+zai auth login groq
+zai model test groq
+```
+
+If external Codex or Claude login fails, use their official CLI directly:
+
+```bash
+codex login
+codex login --device-auth
+claude login
+```
+
+If `codex` or `claude` is not found, install the official CLI first or use a
+provider API key with `zai auth login <provider>`.
+
 For local development:
 
 ```bash
@@ -75,10 +209,51 @@ starting points; OpenAI is paid. Keys are saved locally in `~/.zai/.env`.
 Inside interactive mode, type `/` and press Tab to see slash commands, or run
 `/help` and `/commands`.
 
+## Project memory
+
+`zai` can keep small project-specific memory in the folder you run it from:
+
+```text
+.zai/project_memory.json
+```
+
+This is separate from conversation session history. It stores a compact summary
+of project signals such as languages, frameworks, important files, common setup,
+test, and run commands, plus facts you explicitly ask `zai` to remember. It does
+not store API keys, `.env` contents, tokens, passwords, or full source files.
+
+Create or refresh memory:
+
+```bash
+zai memory refresh
+zai memory project
+```
+
+Inside interactive mode:
+
+```text
+/memory project       Show project memory
+/memory refresh       Refresh detected project summary
+/remember <fact>      Save a project fact
+/forget <fact-or-id>  Delete a saved fact
+```
+
+When `zai` starts in a folder that already has `.zai/project_memory.json`, it
+loads a short pinned summary so future answers can use that folder's context.
+Different folders keep different memories.
+
+Memory types:
+
+- Session history: previous conversation messages saved globally under `~/.zai`.
+- Project memory: small per-folder facts in `.zai/project_memory.json`.
+- Repo map: generated structure summary used for repository questions; it is not
+  long-term memory.
+
 ## Main commands
 
 ```text
 zai                         Start the interactive project assistant
+zai doctor                  Check install, keys, and provider readiness
 zai commands                List interactive slash commands
 zai ask <message>           Send a one-off message
 zai chat [message]          Chat with the configured model
@@ -112,8 +287,16 @@ zai model remove <name>     Remove a custom model alias
 zai model configure <name>  Set timeout and retry policy
 zai model info <name>       Show effective model configuration
 zai model test <name>       Verify credentials and model availability
+zai auth status             Show API-key and external CLI auth status
+zai auth login <provider>   Connect a provider API key
+zai auth logout <provider>  Remove a provider API key from zai
+zai auth doctor             Show auth troubleshooting guidance
 zai memory show             Show last task metadata
 zai memory projects         List remembered projects
+zai memory project          Show project-scoped memory
+zai memory refresh          Create or refresh project-scoped memory
+zai memory remember <fact>  Save a project fact
+zai memory forget <id/text> Delete a project fact
 zai memory clear            Clear memory metadata
 
 zai hook list

zai_cli-0.1.7/tests/test_auth.py

@@ -0,0 +1,157 @@
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from zai.cli.settings import register_settings_commands
+from zai.core import auth as auth_mod
+from zai.core.auth import (
+    auth_status,
+    delete_provider_key,
+    external_login_command,
+    mask_secret,
+    save_provider_key,
+    validate_provider,
+)
+
+
+def auth_app():
+    app = typer.Typer()
+    register_settings_commands(app)
+    return app
+
+
+def test_mask_secret_never_returns_full_value():
+    assert mask_secret("sk-123456789") == "sk-…6789"
+    assert mask_secret("short") == "••••"
+
+
+def test_save_and_delete_provider_key(tmp_path, monkeypatch):
+    import zai.config as config_mod
+
+    monkeypatch.setattr(config_mod, "ENV_FILE", tmp_path / ".env")
+    monkeypatch.setattr(auth_mod, "ENV_FILE", tmp_path / ".env")
+    monkeypatch.delenv("GROQ_API_KEY", raising=False)
+
+    assert save_provider_key("groq", "groq-secret")
+    assert "GROQ_API_KEY=groq-secret" in (tmp_path / ".env").read_text()
+
+    assert delete_provider_key("groq")
+    assert "groq-secret" not in (tmp_path / ".env").read_text()
+
+
+def test_auth_status_with_and_without_keys(monkeypatch):
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    missing = next(row for row in auth_status("gemini") if row["provider"] == "gemini")
+    monkeypatch.setenv("GEMINI_API_KEY", "gemini-secret")
+    present = next(row for row in auth_status("gemini") if row["provider"] == "gemini")
+
+    assert missing["key_status"] == "missing"
+    assert present["key_status"] == "set in environment"
+    assert "gemini-secret" not in str(present)
+
+
+def test_external_login_command_for_codex_and_claude():
+    assert external_login_command("openai") == ["codex", "login"]
+    assert external_login_command("openai", device=True) == [
+        "codex",
+        "login",
+        "--device-auth",
+    ]
+    assert external_login_command("anthropic") == ["claude", "login"]
+
+
+def test_validate_provider_normalizes_results():
+    provider = MagicMock()
+    provider.is_available.return_value = True
+    provider.chat.return_value = MagicMock()
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        assert validate_provider("groq") == "OK"
+
+    provider.chat.side_effect = RuntimeError("unauthorized api key")
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        assert validate_provider("groq") == "invalid"
+
+    provider.chat.side_effect = RuntimeError("rate limit")
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        assert validate_provider("groq") == "quota/rate limit"
+
+
+def test_top_level_auth_status_does_not_print_secret(monkeypatch):
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-live-secret")
+
+    result = CliRunner().invoke(auth_app(), ["auth", "status", "openai"])
+
+    assert result.exit_code == 0
+    assert "Authentication status" in result.output
+    assert "openai" in result.output
+    assert "sk-live-secret" not in result.output
+
+
+@pytest.mark.parametrize(
+    ("provider", "label"),
+    [
+        ("gemini", "Gemini"),
+        ("groq", "Groq"),
+        ("openai", "OpenAI"),
+        ("anthropic", "Anthropic Claude"),
+    ],
+)
+def test_top_level_auth_login_saves_api_key(provider, label):
+    app = auth_app()
+    with (
+        patch("zai.cli.settings.Prompt.ask", return_value=f"{provider}-key"),
+        patch("zai.cli.settings.Confirm.ask", return_value=False),
+        patch("zai.cli.settings.save_provider_key", return_value=True) as save,
+    ):
+        result = CliRunner().invoke(app, ["auth", "login", provider])
+
+    assert result.exit_code == 0
+    save.assert_called_once_with(provider, f"{provider}-key")
+    assert f"Saved {label} API key" in result.output
+    assert f"{provider}-key" not in result.output
+
+
+def test_top_level_auth_external_cli_requires_confirmation():
+    app = auth_app()
+    completed = MagicMock(returncode=0)
+    with (
+        patch("zai.cli.settings.Prompt.ask", return_value=""),
+        patch("zai.cli.settings.Confirm.ask", return_value=True),
+        patch("zai.cli.settings.run_external_login", return_value=completed) as run,
+    ):
+        result = CliRunner().invoke(app, ["auth", "login", "openai"])
+
+    assert result.exit_code == 0
+    run.assert_called_once_with("openai", device=False)
+    assert "External CLI login finished" in result.output
+
+
+def test_top_level_auth_logout_removes_key():
+    with patch("zai.cli.settings.delete_provider_key", return_value=True) as delete:
+        result = CliRunner().invoke(auth_app(), ["auth", "logout", "groq"])
+
+    assert result.exit_code == 0
+    delete.assert_called_once_with("groq")
+    assert "Removed Groq API key" in result.output
+
+
+@pytest.mark.parametrize(
+    ("provider_name", "command"),
+    [("openai", "codex"), ("anthropic", "claude")],
+)
+def test_external_cli_auth_cache_detected(provider_name, command, tmp_path, monkeypatch):
+    cache = tmp_path / "auth.json"
+    cache.write_text("{}", encoding="utf-8")
+    provider = auth_mod.PROVIDERS[provider_name]
+    replacement = auth_mod.AuthProvider(
+        **{**provider.__dict__, "cli_auth_paths": (cache,)}
+    )
+    monkeypatch.setitem(auth_mod.PROVIDERS, provider_name, replacement)
+    monkeypatch.setattr(auth_mod, "which", lambda value: str(Path(command)))
+
+    row = auth_status(provider_name)[0]
+
+    assert row["external_status"] == "external cli auth cache present"

{zai_cli-0.1.3 → zai_cli-0.1.7}/tests/test_config_main.py

@@ -262,7 +262,7 @@ def test_zai_help_shows_all_commands():
         capture_output=True, text=True, encoding="utf-8", errors="replace",
     )
     output = re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", result.stdout)
-    for cmd in ["chat", "ask", "commands", "search", "file", "git", "repo", "vision", "browser", "skill", "hook", "mcp", "session"]:
+    for cmd in ["chat", "ask", "commands", "doctor", "auth", "search", "file", "git", "repo", "vision", "browser", "skill", "hook", "mcp", "session"]:
         assert cmd in output, f"Command missing from --help: {cmd}"
     assert "--debug" in output
     assert "--plain" in output

{zai_cli-0.1.3 → zai_cli-0.1.7}/tests/test_input.py

@@ -25,6 +25,33 @@ def test_model_completion():
     assert ("groq", "groq", "model") in candidates
 
 
+def test_memory_completion():
+    candidates = completion_candidates(
+        "/memory r",
+        ".",
+        {"memory"},
+    )
+
+    assert candidates == [("refresh", "refresh", "memory action")]
+
+
+def test_auth_completion():
+    actions = completion_candidates(
+        "/auth l",
+        ".",
+        {"auth"},
+    )
+    providers = completion_candidates(
+        "/auth login g",
+        ".",
+        {"auth"},
+    )
+
+    assert ("login", "login", "auth action") in actions
+    assert ("gemini", "gemini", "auth provider") in providers
+    assert ("groq", "groq", "auth provider") in providers
+
+
 def test_session_completion():
     candidates = completion_candidates(
         "/resume proj",