zai-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{zai_cli-0.1.0 → zai_cli-0.1.2}/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.2] - 2026-06-24
+
+### Changed
+
+- Improved interactive slash-command discovery: typing `/` now shows the
+  commands menu.
+- Improved interactive model discovery: bare `/model` now shows the model list.
+- Clarified the interactive startup hint to point users at `/` and `/help`.
+
+### Fixed
+
+- Prevented common help words such as `commands`, `setup`, and `model list`
+  from being sent to the AI as ordinary project requests.
+
+## [0.1.1] - 2026-06-24
+
+### Added
+
+- Added `zai commands` so new users can discover interactive slash commands
+  before entering the interactive shell.
+- Added `zai setup` onboarding text with recommended free providers, API-key
+  links, and the local key storage path.
+
+### Documentation
+
+- Expanded quick-start guidance for slash commands and provider key setup.
+
 ## [0.1.0] - 2026-06-23
 
 ### Added

{zai_cli-0.1.0/zai_cli.egg-info → zai_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -103,6 +103,9 @@ quota or download/start external tools.
 # Configure providers
 zai setup
 
+# See which slash commands are available before entering interactive mode
+zai commands
+
 # Start the interactive coding assistant in the current directory
 zai
 
@@ -119,10 +122,21 @@ zai run script.py
 zai git status
 ```
 
+During `zai setup`, add at least one API key. Gemini and Groq are good free
+starting points; OpenAI is paid. Keys are saved locally in `~/.zai/.env`.
+
+- Gemini key: <https://aistudio.google.com/app/apikey>
+- Groq key: <https://console.groq.com/keys>
+- OpenAI key: <https://platform.openai.com/api-keys>
+
+Inside interactive mode, type `/` and press Tab to see slash commands, or run
+`/help` and `/commands`.
+
 ## Main commands
 
 ```text
 zai                         Start the interactive project assistant
+zai commands                List interactive slash commands
 zai ask <message>           Send a one-off message
 zai chat [message]          Chat with the configured model
 zai --plain ask <message>   Emit only plain final response text

{zai_cli-0.1.0 → zai_cli-0.1.2}/README.md

@@ -46,6 +46,9 @@ quota or download/start external tools.
 # Configure providers
 zai setup
 
+# See which slash commands are available before entering interactive mode
+zai commands
+
 # Start the interactive coding assistant in the current directory
 zai
 
@@ -62,10 +65,21 @@ zai run script.py
 zai git status
 ```
 
+During `zai setup`, add at least one API key. Gemini and Groq are good free
+starting points; OpenAI is paid. Keys are saved locally in `~/.zai/.env`.
+
+- Gemini key: <https://aistudio.google.com/app/apikey>
+- Groq key: <https://console.groq.com/keys>
+- OpenAI key: <https://platform.openai.com/api-keys>
+
+Inside interactive mode, type `/` and press Tab to see slash commands, or run
+`/help` and `/commands`.
+
 ## Main commands
 
 ```text
 zai                         Start the interactive project assistant
+zai commands                List interactive slash commands
 zai ask <message>           Send a one-off message
 zai chat [message]          Chat with the configured model
 zai --plain ask <message>   Emit only plain final response text

{zai_cli-0.1.0 → zai_cli-0.1.2}/tests/test_config_main.py

@@ -262,12 +262,24 @@ 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", "search", "file", "git", "repo", "vision", "browser", "skill", "hook", "mcp", "session"]:
+    for cmd in ["chat", "ask", "commands", "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
 
 
+def test_top_level_commands_lists_slash_commands():
+    from typer.testing import CliRunner
+    from zai.main import app
+
+    result = CliRunner().invoke(app, ["commands"])
+
+    assert result.exit_code == 0
+    assert "Slash commands" in result.output
+    assert "/review" in result.output
+    assert "/commands" in result.output
+
+
 def test_top_level_session_list(tmp_path, monkeypatch):
     from typer.testing import CliRunner
     import zai.core.session as session_mod

{zai_cli-0.1.0 → zai_cli-0.1.2}/tests/test_input.py

@@ -11,7 +11,7 @@ def test_slash_command_completion():
         {"resume", "review", "help"},
     )
 
-    assert candidates == [("/resume", "/resume", "command")]
+    assert candidates == [("/resume", "/resume", "slash command")]
 
 
 def test_model_completion():

{zai_cli-0.1.0 → zai_cli-0.1.2}/tests/test_interactive.py

@@ -1,6 +1,10 @@
 from unittest.mock import patch
 
-from zai.cli.interactive import _correct_slash_command, run_interactive
+from zai.cli.interactive import (
+    _correct_slash_command,
+    _normalize_plain_command,
+    run_interactive,
+)
 
 
 def test_slash_command_typo_is_corrected():
@@ -14,6 +18,35 @@ def test_slash_command_typo_is_corrected():
     assert corrected == "/resume"
 
 
+def test_plain_command_aliases_do_not_go_to_ai():
+    assert _normalize_plain_command("/") == "/commands"
+    assert _normalize_plain_command("commands") == "/commands"
+    assert _normalize_plain_command("setup") == "/setup"
+    assert _normalize_plain_command("model list") == "/model list"
+    assert _normalize_plain_command("build a login page") == "build a login page"
+
+
+def test_interactive_plain_commands_show_local_help(tmp_path, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    with patch("zai.cli.interactive.has_available_provider", return_value=True):
+        with patch("zai.cli.interactive.fire_hook", return_value=True):
+            with patch("zai.cli.interactive.plugin_loader.load_all", return_value={}):
+                with patch("zai.cli.interactive.plugin_loader.get_errors", return_value={}):
+                    with patch("zai.cli.interactive._connect_mcp_servers"):
+                        with patch(
+                            "zai.cli.interactive.InteractiveInput.prompt",
+                            side_effect=["/", "commands", "setup", "/model", EOFError()],
+                        ):
+                            with patch("zai.cli.interactive.run_agent") as run_agent:
+                                run_interactive("groq")
+
+    output = capsys.readouterr().out
+    assert "Interactive slash commands" in output
+    assert "API key setup" in output
+    assert "Available models" in output
+    run_agent.assert_not_called()
+
+
 def test_interactive_help_then_exit(tmp_path, monkeypatch, capsys):
     monkeypatch.chdir(tmp_path)
     with patch("zai.cli.interactive.has_available_provider", return_value=True):

{zai_cli-0.1.0 → zai_cli-0.1.2}/tests/test_settings_cli.py

@@ -25,6 +25,8 @@ def test_setup_keeps_existing_keys_and_selects_default():
         result = CliRunner().invoke(app, ["setup"])
 
     assert result.exit_code == 0
+    assert "New user quick start" in result.output
+    assert "aistudio.google.com" in result.output
     assert "already set" in result.output
     assert "zai is ready" in result.output
     assert config["default_model"] == "groq"

zai_cli-0.1.2/zai/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

{zai_cli-0.1.0 → zai_cli-0.1.2}/zai/cli/interactive.py

@@ -36,7 +36,41 @@ console = Console()
 CORE_COMMANDS = {
     "help", "clear", "files", "diff", "undo", "plan", "test",
     "watch", "commit", "review", "fix", "explain", "feature",
-    "session", "resume", "model", "memory", "commands",
+    "session", "resume", "model", "memory", "commands", "setup",
+}
+
+INTERACTIVE_COMMANDS = [
+    ("/help", "Show interactive help"),
+    ("/commands", "List built-in and plugin slash commands"),
+    ("/setup", "Show API-key setup instructions"),
+    ("/clear", "Clear the terminal"),
+    ("/files", "List files in the current folder"),
+    ("/diff", "Show git diff"),
+    ("/undo", "Restore the last AI-changed file"),
+    ("/plan <task>", "Plan first, approve, then execute"),
+    ("/test", "Run pytest and auto-fix failures"),
+    ("/watch", "Toggle file-change watcher"),
+    ("/session ...", "Save, load, search, rename, or delete sessions"),
+    ("/resume [name]", "Resume latest or named session"),
+    ("/model list", "Show available models"),
+    ("/model <name>", "Switch model"),
+    ("/memory", "Show last session info"),
+]
+
+PLAIN_COMMAND_ALIASES = {
+    "help": "/help",
+    "commands": "/commands",
+    "command": "/commands",
+    "cmd": "/commands",
+    "setup": "/setup",
+    "keys": "/setup",
+    "api keys": "/setup",
+    "model list": "/model list",
+    "models": "/model list",
+    "memory": "/memory",
+    "files": "/files",
+    "diff": "/diff",
+    "undo": "/undo",
 }
 
 
@@ -76,6 +110,56 @@ def _show_help() -> None:
     )
 
 
+def _show_commands() -> None:
+    table = Table(title="Interactive slash commands", border_style="cyan")
+    table.add_column("Command", style="cyan")
+    table.add_column("Description")
+    for name, description in INTERACTIVE_COMMANDS:
+        table.add_row(name, description)
+    for command in list_commands():
+        table.add_row(f"/{command['name']}", command["description"])
+    for name, data in plugin_loader.get_all_commands().items():
+        table.add_row(f"/{name}", f"{data.get('description', '')} (plugin)")
+    console.print(table)
+    console.print("[dim]Tip: type / and press Tab to autocomplete commands.[/dim]")
+
+
+def _show_setup_hint() -> None:
+    console.print(Panel(
+        "[bold cyan]API key setup[/bold cyan]\n"
+        "Exit this chat with Ctrl+C, then run:\n\n"
+        "[bold]zai setup[/bold]\n\n"
+        "Good free starting points:\n"
+        "- Gemini: https://aistudio.google.com/app/apikey\n"
+        "- Groq: https://console.groq.com/keys\n"
+        "Paid option:\n"
+        "- OpenAI: https://platform.openai.com/api-keys\n\n"
+        "Keys are saved locally in ~/.zai/.env. After setup, run:\n"
+        "[bold]zai model list[/bold]",
+        border_style="cyan",
+    ))
+
+
+def _show_models() -> None:
+    table = Table(title="Available models", border_style="cyan")
+    table.add_column("Name", style="cyan")
+    table.add_column("Model")
+    table.add_column("Key")
+    for key, data in get_models().items():
+        key_status = "ok" if get_api_key(data["provider"]) else "no key"
+        table.add_row(key, data["name"], key_status)
+    console.print(table)
+
+
+def _normalize_plain_command(message: str) -> str:
+    stripped = message.strip()
+    if stripped == "/":
+        return "/commands"
+    if stripped.startswith("/") or not stripped:
+        return message
+    return PLAIN_COMMAND_ALIASES.get(stripped.lower(), message)
+
+
 def _correct_slash_command(message: str) -> str:
     stripped = message.strip()
     if not stripped.startswith("/") or stripped.startswith("//"):
@@ -173,7 +257,7 @@ def run_interactive(model: str = None) -> None:
         f"[dim]Folder: {cwd}[/dim]\n"
         f"[dim]Files: {', '.join(visible[:12])}"
         f"{'...' if len(visible) > 12 else ''}[/dim]\n"
-        "[dim]Ctrl+C to exit  |  /help for commands[/dim]",
+        "[dim]Ctrl+C to exit  |  type / for commands  |  /help for help[/dim]",
         border_style="cyan",
     ))
 
@@ -254,26 +338,23 @@ def run_interactive(model: str = None) -> None:
             if not message.strip():
                 continue
             message = _correct_slash_command(message)
+            message = _normalize_plain_command(message)
             stripped = message.strip()
 
             if stripped == "/help":
                 _show_help()
+            elif stripped == "/commands":
+                _show_commands()
+            elif stripped == "/setup":
+                _show_setup_hint()
             elif stripped == "/clear":
                 console.clear()
             elif stripped == "/files":
                 _show_files(cwd)
-            elif stripped.startswith("/model "):
-                name = stripped.split(" ", 1)[1].strip()
+            elif stripped == "/model" or stripped.startswith("/model "):
+                name = stripped.split(" ", 1)[1].strip() if " " in stripped else "list"
                 if name == "list":
-                    for key, data in get_models().items():
-                        key_status = (
-                            "[green]ok[/green]"
-                            if get_api_key(data["provider"])
-                            else "[red]no key[/red]"
-                        )
-                        console.print(
-                            f"  [cyan]{key}[/cyan] — {data['name']} ({key_status})"
-                        )
+                    _show_models()
                 elif name in get_models():
                     preferred = name
                     session_context.set_model(name)
@@ -490,16 +571,9 @@ def run_interactive(model: str = None) -> None:
                         )
                         save_session(task=f"/{command_name}", model=preferred)
                 elif command_name == "commands":
-                    for command in list_commands():
-                        console.print(
-                            f"  [cyan]/{command['name']}[/cyan] — "
-                            f"{command['description']}"
-                        )
-                    for name, data in plugin_loader.get_all_commands().items():
-                        console.print(
-                            f"  [blue]/{name}[/blue] — "
-                            f"{data.get('description', '')} [dim](plugin)[/dim]"
-                        )
+                    _show_commands()
+                elif command_name == "setup":
+                    _show_setup_hint()
                 else:
                     console.print(f"[red]Unknown command: /{command_name}[/red]")
                     console.print("[dim]Type /commands to see available commands[/dim]")

{zai_cli-0.1.0 → zai_cli-0.1.2}/zai/cli/settings.py

@@ -8,6 +8,7 @@ from rich.prompt import Confirm, Prompt
 from rich.table import Table
 
 from ..config import (
+    ENV_FILE,
     MEMORY_FILE,
     MODELS,
     get_api_key,
@@ -41,6 +42,16 @@ console = Console()
 def setup():
     """Setup API keys and preferences."""
     console.print(Panel("[bold cyan]Welcome to zai setup![/bold cyan]", border_style="cyan"))
+    console.print(
+        "[cyan]New user quick start:[/cyan] add at least one API key. "
+        "Gemini or Groq are good free starting points; OpenAI is paid."
+    )
+    console.print(f"[dim]Keys are saved locally in {ENV_FILE}[/dim]")
+    console.print(
+        "[dim]Get keys: Gemini https://aistudio.google.com/app/apikey | "
+        "Groq https://console.groq.com/keys | "
+        "OpenAI https://platform.openai.com/api-keys[/dim]"
+    )
     providers = [
         ("gemini", "Google Gemini (FREE — Recommended)"),
         ("groq", "Groq (FREE — Fast)"),

{zai_cli-0.1.0 → zai_cli-0.1.2}/zai/main.py

@@ -4,8 +4,10 @@ from typer.core import TyperGroup
 from rich.console import Console
 from rich.panel import Panel
 from rich.prompt import Prompt, Confirm
+from rich.table import Table
 
 from .config import load_config
+from .core.commands import list_commands as list_slash_commands
 from .core.fallback import (
     format_model_selection,
     has_available_provider,
@@ -22,6 +24,7 @@ from .cli.utilities import register_utility_commands
 from .cli.workflows import register_workflow_commands
 from .cli.common import closest_command as _closest_command
 from .cli.interactive import run_interactive
+from .plugins import loader as plugin_loader
 
 
 class FuzzyTyperGroup(TyperGroup):
@@ -52,6 +55,23 @@ if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
 console = Console()
 
 context = ContextManager()
+INTERACTIVE_COMMANDS = [
+    ("/help", "Show interactive help"),
+    ("/commands", "List built-in and plugin slash commands"),
+    ("/setup", "Show API-key setup instructions"),
+    ("/clear", "Clear the terminal"),
+    ("/files", "List files in the current folder"),
+    ("/diff", "Show git diff"),
+    ("/undo", "Restore the last AI-changed file"),
+    ("/plan <task>", "Plan first, approve, then execute"),
+    ("/test", "Run pytest and auto-fix failures"),
+    ("/watch", "Toggle file-change watcher"),
+    ("/session ...", "Save, load, search, rename, or delete sessions"),
+    ("/resume [name]", "Resume latest or named session"),
+    ("/model list", "Show available models"),
+    ("/model <name>", "Switch model"),
+    ("/memory", "Show last session info"),
+]
 SYSTEM_PROMPT = (
     "You are zai, a smart AI assistant running in the terminal. Be concise, helpful, and direct. "
     "IMPORTANT: When creating files, ALWAYS use this exact format for each file:\n"
@@ -184,6 +204,34 @@ def ask(
     _chat(message, model)
 
 
+@app.command("commands")
+def commands():
+    """List interactive slash commands and where to use them."""
+    console.print(
+        "[cyan]Slash commands are available inside interactive mode.[/cyan]\n"
+        "Run [bold]zai[/bold], then type [bold]/[/bold] and press Tab, or use "
+        "[bold]/help[/bold] and [bold]/commands[/bold]."
+    )
+
+    table = Table(title="Interactive slash commands")
+    table.add_column("Command")
+    table.add_column("Description")
+    for name, description in INTERACTIVE_COMMANDS:
+        table.add_row(name, description)
+    for command in list_slash_commands():
+        table.add_row(f"/{command['name']}", command.get("description", ""))
+    console.print(table)
+
+    plugin_commands = plugin_loader.get_all_commands()
+    if plugin_commands:
+        plugin_table = Table(title="Plugin slash commands")
+        plugin_table.add_column("Command")
+        plugin_table.add_column("Description")
+        for name, data in sorted(plugin_commands.items()):
+            plugin_table.add_row(f"/{name}", data.get("description", ""))
+        console.print(plugin_table)
+
+
 @app.callback(invoke_without_command=True)
 def main(
     ctx: typer.Context,

{zai_cli-0.1.0 → zai_cli-0.1.2}/zai/ui/input.py

@@ -59,7 +59,7 @@ def completion_candidates(
     command_token = parts[0]
     if len(parts) == 1 and not before.endswith(" "):
         return [
-            (f"/{name}", f"/{name}", "command")
+            (f"/{name}", f"/{name}", "slash command")
             for name in sorted(set(commands))
             if f"/{name}".startswith(command_token.lower())
         ]

{zai_cli-0.1.0 → zai_cli-0.1.2/zai_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -103,6 +103,9 @@ quota or download/start external tools.
 # Configure providers
 zai setup
 
+# See which slash commands are available before entering interactive mode
+zai commands
+
 # Start the interactive coding assistant in the current directory
 zai
 
@@ -119,10 +122,21 @@ zai run script.py
 zai git status
 ```
 
+During `zai setup`, add at least one API key. Gemini and Groq are good free
+starting points; OpenAI is paid. Keys are saved locally in `~/.zai/.env`.
+
+- Gemini key: <https://aistudio.google.com/app/apikey>
+- Groq key: <https://console.groq.com/keys>
+- OpenAI key: <https://platform.openai.com/api-keys>
+
+Inside interactive mode, type `/` and press Tab to see slash commands, or run
+`/help` and `/commands`.
+
 ## Main commands
 
 ```text
 zai                         Start the interactive project assistant
+zai commands                List interactive slash commands
 zai ask <message>           Send a one-off message
 zai chat [message]          Chat with the configured model
 zai --plain ask <message>   Emit only plain final response text

zai_cli-0.1.0/zai/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"