q-bot 2.0.0.dev1__tar.gz → 2.0.0.dev2__tar.gz

q_bot-2.0.0.dev2/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: q-bot
+Version: 2.0.0.dev2
+Summary: An LLM agent from the comfort of your command line
+Author-email: Tushar Khan <dev@tusharkhan.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/tk755/q
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic==0.75.0
+Requires-Dist: colorama==0.4.6
+Requires-Dist: distro==1.9.0
+Requires-Dist: openai==2.9.0
+Requires-Dist: psutil==7.2.1
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pyperclip==1.11.0
+Requires-Dist: python-dotenv==1.2.1
+Requires-Dist: termcolor==3.2.0
+
+# Overview
+
+`q` is a provider-agnostic command-line agent and LLM framework.
+
+> I originally built this as a personal CLI tool before Claude Code existed. I still find it more useful for quick shell interactions and running multi-model experiments.
+
+# Installation
+
+Install using any pip-compatible package manager (e.g. `pip`, `pipx`, `uv`, etc.):
+
+```bash
+pipx install q-bot
+```
+
+Requires Python 3.12+.
+
+# CLI Usage
+
+`q` uses a simple paradigm where each character from a-z is mapped to a single flag representing a command or option. This enables concise combinations of flags to achieve complex behavior.
+
+## Flag Reference
+
+| Flag | Name         | Arg     | Description                    | Type    |
+| ---- | ------------ | ------- | ------------------------------ | ------: |
+| `-a` | agent        |         | *[reserved for future use]*    | Command |
+| `-b` | batch        |         | *[reserved for future use]*    |         |
+| `-c` | code         | str     | generate code                  | Command |
+| `-d` | directory    | - / str | add a directory to context     | Option  |
+| `-e` | explain      | - / str | explain code or text           | Command |
+| `-f` | file         | str     | read input from file           | Option  |
+| `-g` |              |         |                                |         |
+| `-h` | help         | - / str | help message / help agent      | Command |
+| `-i` | image        | str     | generate/edit an image         | Command |
+| `-j` | json         | -       | output as JSON                 | Option  |
+| `-k` | api key      | str     | override API key               | Option  |
+| `-l` |              |         |                                |         |
+| `-m` | model        | str     | override model/provider        | Option  |
+| `-n` | new session  | -       | clear the session history      | Option  |
+| `-o` | output       | str     | output file                    | Option  |
+| `-p` |              |         |                                |         |
+| `-q` |              |         |                                |         |
+| `-r` | rag          | - / str | *[reserved for future use]*    | Command |
+| `-s` | shell        | - / str | generate a shell command       | Command |
+| `-t` | text         | str     | generate text                  | Command |
+| `-u` | user command | str     | *[reserved for future use]*    | Command |
+| `-v` | verbose      | -       | debug logging                  | Option  |
+| `-w` | web search   | str     | search the web                 | Command |
+| `-x` | execute      | -       | execute a shell command        | Option  |
+| `-y` |              |         |                                |         |
+| `-z` | undo         | - / int | undo exchanges (default 1)     | Option  |
+
+## Sessions
+
+Each terminal or script that runs `q` maintains an isolated **session** that persists conversation history across calls. Use `-n` to clear the session history for a new conversation or one-shot prompt. Sessions are automatically deleted when the parent shell process exits.
+
+# Library Usage
+
+The `q` library is built on two principles:
+
+**Clients are single-capability.** Each client does one thing (e.g. text generation, image generation, web search, etc.) and has a static return type. No mode switching or tool selection logic is necessary.
+
+**Agents are provider- and capability-agnostic.** Every agent accepts any client and inherits its return type, regardless of what the underlying client does or which provider it calls.
+
+## Clients
+
+A **client** wraps a provider's API for one capability.
+
+Clients extend `Client[T]` and are instantiated with an API key, model name, and optionally provider- and model-specific argument overrides. All clients expose the same `generate` method which returns a value of type `T`:
+
+```python
+Client[T](api_key: str, model: str, **model_args)
+Client[T].generate(messages: list[Message]) -> T
+```
+
+A number of built-in clients with sensible defaults are provided for the following providers and capabilities:
+
+| Client        | T       | Description                  | `openai` | `anthropic` |
+| ------------- | ------- | ---------------------------- | :------: | :---------: |
+| `TextClient`  | `str`   | text generation              | ✓        | ✓           |
+| `WebClient`   | `str`   | web-grounded text generation | ✓        | ✗           |
+| `ImageClient` | `bytes` | image generation             | ✓        | ✗           |
+
+### Dynamic Loading
+
+Client classes are typically imported from their provider module:
+
+```python
+from q.providers.openai import ImageClient
+
+client = ImageClient(api_key, model, **model_args)
+```
+
+They can also be dynamically loaded at runtime by specifying a provider and capability using the `load_client_class` utility:
+
+```python
+from q.providers import load_client_class
+
+client_class = load_client_class('openai', 'ImageClient')
+client = client_class(api_key, model, **model_args)
+```
+
+## Agents
+
+An **agent** manages conversation state and delegates generation to a client.
+
+`ChatAgent[T]` maintains a message history and prepends an optional system prompt:
+
+```python
+ChatAgent[T](client: Client[T], system: str | None = None)
+ChatAgent[T].prompt(text: str) -> T
+```
+
+`BatchAgent[T]` processes multiple inputs concurrently using a shared system prompt, with no conversation history:
+
+```python
+BatchAgent[T](client: Client[T], system: str | None = None)
+BatchAgent[T].batch_prompt(text_list: list[str], n_threads: int = 8) -> list[T]
+```
+
+<!-- ## Examples
+
+This design enables full LLM functionality with minimal code.
+
+**Example 1:** Generate an image via OpenAI
+
+```python
+from q.providers.openai import ImageClient
+from q.agents import ChatAgent
+
+client = ImageClient(api_key, "gpt-image-2", quality="high")
+agent = ChatAgent(client)
+image_bytes = await agent.prompt("a cat in space")
+Path("cat.png").write_bytes(image_bytes)
+```
+
+**Example 2:** Generate batch text via Anthropic
+
+```python
+from q.providers.anthropic import TextClient
+from q.agents import BatchAgent
+
+client = TextClient(api_key, "claude-opus-4-8")
+agent = BatchAgent(client, system="Identify the language of the text.")
+inputs = ["How are you?", "¿Cómo estás?", "Comment ça va?"]
+langs = await agent.batch_prompt(inputs)
+```
+
+**Example 3:** Multi-model orchestration
+
+```python
+from q.providers import load_client_class
+from q.agents import ChatAgent
+
+client1 = load_client_class('openai', 'TextClient')(oai_key, "gpt-5-5")
+client2 = load_client_class('anthropic', 'TextClient')(anthropic_key, "claude-opus-4-8")
+
+system = "You are an AI speaking with another AI. Engage in a discussion about the future of AI."
+
+agent1 = ChatAgent(client1, system=system)
+agent2 = ChatAgent(client2, system=system)
+
+text = "What are your thoughts on the future of AI?"
+
+for _ in range(5):
+    text = await agent1.prompt(text)
+    print("agent1:", text)
+    text = await agent2.prompt(text)
+    print("agent2:", text)
+``` -->

q_bot-2.0.0.dev2/README.md

@@ -0,0 +1,169 @@
+# Overview
+
+`q` is a provider-agnostic command-line agent and LLM framework.
+
+> I originally built this as a personal CLI tool before Claude Code existed. I still find it more useful for quick shell interactions and running multi-model experiments.
+
+# Installation
+
+Install using any pip-compatible package manager (e.g. `pip`, `pipx`, `uv`, etc.):
+
+```bash
+pipx install q-bot
+```
+
+Requires Python 3.12+.
+
+# CLI Usage
+
+`q` uses a simple paradigm where each character from a-z is mapped to a single flag representing a command or option. This enables concise combinations of flags to achieve complex behavior.
+
+## Flag Reference
+
+| Flag | Name         | Arg     | Description                    | Type    |
+| ---- | ------------ | ------- | ------------------------------ | ------: |
+| `-a` | agent        |         | *[reserved for future use]*    | Command |
+| `-b` | batch        |         | *[reserved for future use]*    |         |
+| `-c` | code         | str     | generate code                  | Command |
+| `-d` | directory    | - / str | add a directory to context     | Option  |
+| `-e` | explain      | - / str | explain code or text           | Command |
+| `-f` | file         | str     | read input from file           | Option  |
+| `-g` |              |         |                                |         |
+| `-h` | help         | - / str | help message / help agent      | Command |
+| `-i` | image        | str     | generate/edit an image         | Command |
+| `-j` | json         | -       | output as JSON                 | Option  |
+| `-k` | api key      | str     | override API key               | Option  |
+| `-l` |              |         |                                |         |
+| `-m` | model        | str     | override model/provider        | Option  |
+| `-n` | new session  | -       | clear the session history      | Option  |
+| `-o` | output       | str     | output file                    | Option  |
+| `-p` |              |         |                                |         |
+| `-q` |              |         |                                |         |
+| `-r` | rag          | - / str | *[reserved for future use]*    | Command |
+| `-s` | shell        | - / str | generate a shell command       | Command |
+| `-t` | text         | str     | generate text                  | Command |
+| `-u` | user command | str     | *[reserved for future use]*    | Command |
+| `-v` | verbose      | -       | debug logging                  | Option  |
+| `-w` | web search   | str     | search the web                 | Command |
+| `-x` | execute      | -       | execute a shell command        | Option  |
+| `-y` |              |         |                                |         |
+| `-z` | undo         | - / int | undo exchanges (default 1)     | Option  |
+
+## Sessions
+
+Each terminal or script that runs `q` maintains an isolated **session** that persists conversation history across calls. Use `-n` to clear the session history for a new conversation or one-shot prompt. Sessions are automatically deleted when the parent shell process exits.
+
+# Library Usage
+
+The `q` library is built on two principles:
+
+**Clients are single-capability.** Each client does one thing (e.g. text generation, image generation, web search, etc.) and has a static return type. No mode switching or tool selection logic is necessary.
+
+**Agents are provider- and capability-agnostic.** Every agent accepts any client and inherits its return type, regardless of what the underlying client does or which provider it calls.
+
+## Clients
+
+A **client** wraps a provider's API for one capability.
+
+Clients extend `Client[T]` and are instantiated with an API key, model name, and optionally provider- and model-specific argument overrides. All clients expose the same `generate` method which returns a value of type `T`:
+
+```python
+Client[T](api_key: str, model: str, **model_args)
+Client[T].generate(messages: list[Message]) -> T
+```
+
+A number of built-in clients with sensible defaults are provided for the following providers and capabilities:
+
+| Client        | T       | Description                  | `openai` | `anthropic` |
+| ------------- | ------- | ---------------------------- | :------: | :---------: |
+| `TextClient`  | `str`   | text generation              | ✓        | ✓           |
+| `WebClient`   | `str`   | web-grounded text generation | ✓        | ✗           |
+| `ImageClient` | `bytes` | image generation             | ✓        | ✗           |
+
+### Dynamic Loading
+
+Client classes are typically imported from their provider module:
+
+```python
+from q.providers.openai import ImageClient
+
+client = ImageClient(api_key, model, **model_args)
+```
+
+They can also be dynamically loaded at runtime by specifying a provider and capability using the `load_client_class` utility:
+
+```python
+from q.providers import load_client_class
+
+client_class = load_client_class('openai', 'ImageClient')
+client = client_class(api_key, model, **model_args)
+```
+
+## Agents
+
+An **agent** manages conversation state and delegates generation to a client.
+
+`ChatAgent[T]` maintains a message history and prepends an optional system prompt:
+
+```python
+ChatAgent[T](client: Client[T], system: str | None = None)
+ChatAgent[T].prompt(text: str) -> T
+```
+
+`BatchAgent[T]` processes multiple inputs concurrently using a shared system prompt, with no conversation history:
+
+```python
+BatchAgent[T](client: Client[T], system: str | None = None)
+BatchAgent[T].batch_prompt(text_list: list[str], n_threads: int = 8) -> list[T]
+```
+
+<!-- ## Examples
+
+This design enables full LLM functionality with minimal code.
+
+**Example 1:** Generate an image via OpenAI
+
+```python
+from q.providers.openai import ImageClient
+from q.agents import ChatAgent
+
+client = ImageClient(api_key, "gpt-image-2", quality="high")
+agent = ChatAgent(client)
+image_bytes = await agent.prompt("a cat in space")
+Path("cat.png").write_bytes(image_bytes)
+```
+
+**Example 2:** Generate batch text via Anthropic
+
+```python
+from q.providers.anthropic import TextClient
+from q.agents import BatchAgent
+
+client = TextClient(api_key, "claude-opus-4-8")
+agent = BatchAgent(client, system="Identify the language of the text.")
+inputs = ["How are you?", "¿Cómo estás?", "Comment ça va?"]
+langs = await agent.batch_prompt(inputs)
+```
+
+**Example 3:** Multi-model orchestration
+
+```python
+from q.providers import load_client_class
+from q.agents import ChatAgent
+
+client1 = load_client_class('openai', 'TextClient')(oai_key, "gpt-5-5")
+client2 = load_client_class('anthropic', 'TextClient')(anthropic_key, "claude-opus-4-8")
+
+system = "You are an AI speaking with another AI. Engage in a discussion about the future of AI."
+
+agent1 = ChatAgent(client1, system=system)
+agent2 = ChatAgent(client2, system=system)
+
+text = "What are your thoughts on the future of AI?"
+
+for _ in range(5):
+    text = await agent1.prompt(text)
+    print("agent1:", text)
+    text = await agent2.prompt(text)
+    print("agent2:", text)
+``` -->

{q_bot-2.0.0.dev1 → q_bot-2.0.0.dev2}/pyproject.toml

@@ -11,8 +11,8 @@ dependencies = [
     "anthropic==0.75.0",
     "colorama==0.4.6",
     "distro==1.9.0",
-    "humanize==4.14.0",
     "openai==2.9.0",
+    "psutil==7.2.1",
     "pydantic==2.12.5",
     "pyperclip==1.11.0",
     "python-dotenv==1.2.1",

q_bot-2.0.0.dev2/q/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0.dev2"

{q_bot-2.0.0.dev1 → q_bot-2.0.0.dev2}/q/cli/commands.py

@@ -4,7 +4,6 @@ import asyncio
 import contextlib
 import os
 import platform
-import shutil
 import string
 import subprocess
 import sys
@@ -13,7 +12,6 @@ from enum import Enum
 from pathlib import Path
 
 import distro
-import humanize
 import pyperclip
 from termcolor import colored
 
@@ -21,10 +19,9 @@ from q import __version__
 from q.providers import load_client_class
 
 from ..agents import ChatAgent
-from ..message import Role
 from .models import Tier, resolve_model_arg
-from .session import SessionManager
-from .terminal import UserError, format_response, qprint
+from .session import StateManager
+from .terminal import InputError, format_response, qprint
 
 # region Registry
 
@@ -33,7 +30,7 @@ OPTIONS: list[type[Flag]] = []
 
 
 def get_default_command() -> type[Command]:
-    char = SessionManager.load_command_char()
+    char = StateManager.load_command_char()
     if char:
         for cmd in COMMANDS:
             if cmd.char == char:
@@ -93,22 +90,19 @@ class Command(Flag):
 class AgentCommand(Command):
     """Base class for commands that prompt an agent."""
 
-    client_str: str = "TextClient"
     tier: Tier
+    client_str: str = "TextClient"
     system: str | None = None
     clip: bool = False
 
     async def execute(self) -> None:
-        if "n" in self.args:
-            SessionManager.new_session()
-
         # resolve provider, model, and model args
-        default_provider = SessionManager.load_default_provider()
+        default_provider = StateManager.load_default_provider()
         provider, model, model_args = resolve_model_arg(self.args.get("m"), self.tier, default_provider)
 
         # create client dynamically
         client_class = load_client_class(provider, self.client_str)
-        api_key = SessionManager.load_api_key(provider)
+        api_key = self.args.get("k") or StateManager.load_api_key(provider)
         client = client_class(api_key, model, **model_args)
 
         if "v" in self.args:
@@ -120,17 +114,17 @@ class AgentCommand(Command):
                     qprint(f"{k}: ", color="green", file=sys.stderr, end="")
                     qprint(f"{v}", file=sys.stderr)
 
-        # resolve system prompt (command's system overrides saved system)
-        system = self.system if self.system is not None else SessionManager.load_system()
-
         # create agent
-        agent = ChatAgent(client, system, SessionManager.load_messages())
+        messages = [] if "n" in self.args else StateManager.load_messages()
+        agent = ChatAgent(client, self.system, messages)
         if "z" in self.args:
             agent.drop_exchanges(self.args["z"])
 
-        # prompt agent and save session
+        # prompt agent
         response = await agent.prompt(self.args[self.char])
-        SessionManager.save_session(agent.system, agent.messages, self.char)
+        
+        # save session
+        StateManager.save_session(self.char, agent.messages)
 
         if "v" in self.args:
             qprint("\nMESSAGES:", color="cyan", file=sys.stderr)
@@ -179,6 +173,7 @@ class ExplainCommand(AgentCommand):
     char = "e"
     desc = "explain"
     value_type = ValueType.TEXT
+    required = True
     tier = Tier.HIGH
     system = "You are a programming assistant. Given a shell command, code snippet, or technical concept, provide a concise and technical explanation. Assume the reader is an experienced developer. Avoid restating the code or command. Avoid explaining obvious syntax. Avoid breaking the answer into bullet points unless necessary. The response should be a single short paragraph optimized for clarity."
 
@@ -193,7 +188,7 @@ class CodeCommand(AgentCommand):
 
     @property
     def system(self) -> str:
-        return f"You are a coding assistant. Given a natural language description, generate a code snippet that accomplishes the requested task. The code should be correct, efficient, concise, and idiomatic. Respond with only the code snippet, without explanations, additional text, or formatting. Assume the programming language is {SessionManager.load_code_lang()} unless otherwise specified."
+        return f"You are a coding assistant. Given a natural language description, generate a code snippet that accomplishes the requested task. The code should be correct, efficient, concise, and idiomatic. Respond with only the code snippet, without explanations, additional text, or formatting. Assume the programming language is {StateManager.load_code_lang()} unless otherwise specified."
 
 
 class ShellCommand(AgentCommand):
@@ -227,7 +222,7 @@ class ShellCommand(AgentCommand):
             cmd = os.environ.get("Q_CMD", None)
             exit_code = os.environ.get("Q_EXIT", None)
             if cmd is None or exit_code is None:
-                raise UserError(
+                raise InputError(
                     "q -s without a prompt requires shell integration. Add to ~/.bashrc:\n"
                     '    q() { Q_EXIT=$? Q_CMD=$(fc -ln -1) command q "$@"; }'
                 )
@@ -337,46 +332,6 @@ class HelpCommand(AgentCommand):
         return "\n".join(lines)
 
 
-class LoadCommand(Command):
-    char = "l"
-    desc = "load session"
-    value_type = ValueType.INT
-
-    async def execute(self) -> None:
-        session_id = self.args.get(self.char)
-        if session_id is None:
-            self._print_session_list()
-        elif not SessionManager.switch_session(session_id):
-            raise UserError(f"invalid session: {session_id}")
-        else:
-            qprint(f"Loaded session {session_id}", color="yellow", file=sys.stderr)
-
-    def _print_session_list(self) -> None:
-        sessions = SessionManager.list_sessions()
-        if not sessions:
-            qprint("No sessions found.")
-            return
-
-        current_id = SessionManager.load_session_id()
-        term_width = shutil.get_terminal_size().columns
-
-        for s in sessions:
-            age = humanize.naturaltime(s.updated) if s.updated else "unknown"
-            prefix_len = len(f"    {s.id}.  ")
-            suffix_len = len(f" ({age})")
-            max_len = max(20, term_width - prefix_len - suffix_len - 5)
-
-            preview = "(empty)"
-            for msg in reversed(s.messages):
-                if msg.role == Role.USER:
-                    preview = msg.content[:max_len] + "..." if len(msg.content) > max_len else msg.content
-                    break
-
-            line = f"    {s.id}.  {preview} ({age})"
-            color = None if s.id == current_id else "dark_grey"
-            qprint(line, color=color)
-
-
 # region Options
 
 
@@ -398,6 +353,13 @@ class JsonOption(Flag):
     desc = "json"
 
 
+class KeyOption(Flag):
+    char = "k"
+    desc = "api key"
+    value_type = ValueType.STR
+    required = True
+
+
 class ModelOption(Flag):
     char = "m"
     desc = "model"

{q_bot-2.0.0.dev1 → q_bot-2.0.0.dev2}/q/cli/main.py

@@ -1,21 +1,17 @@
 import asyncio
-import os
 import sys
-from pathlib import Path
 
 from .parser import parse
-from .terminal import UserError, is_terminal, qprint
+from .session import StateManager
+from .terminal import InputError, qprint
 
 
 def main():
-    # suppress stderr when piped
-    if not is_terminal():
-        sys.stderr = Path(os.devnull).open("w") # noqa: SIM115
-
     try:
         command = parse(sys.argv[1:])
+        StateManager.reap_sessions()
         asyncio.run(command.execute())
-    except (UserError, ImportError) as e:
+    except (InputError, ImportError) as e:
         qprint(str(e), color="red", file=sys.stderr)
         sys.exit(1)
     except KeyboardInterrupt:

{q_bot-2.0.0.dev1 → q_bot-2.0.0.dev2}/q/cli/models.py

@@ -1,7 +1,7 @@
 import contextlib
 from enum import Enum
 
-from .terminal import UserError
+from .terminal import InputError
 
 
 class Tier(Enum):
@@ -57,7 +57,7 @@ MODELS = {
 
 def _lookup(provider: str, tier: Tier) -> tuple[str, str, dict]:
     if provider not in MODELS:
-        raise UserError(f"unknown provider: {provider}")
+        raise InputError(f"unknown provider: {provider}")
 
     config = MODELS[provider][tier]
     model = config["model"]
@@ -87,4 +87,4 @@ def resolve_model_arg(arg: str | None, default_tier: Tier, default_provider: str
     if arg in MODELS:
         return _lookup(arg, default_tier)
 
-    raise UserError(f"invalid model: {arg}")
+    raise InputError(f"invalid model: {arg}")

{q_bot-2.0.0.dev1 → q_bot-2.0.0.dev2}/q/cli/parser.py

@@ -1,7 +1,7 @@
 import re
 
-from .commands import COMMANDS, OPTIONS, ArgMap, Command, Flag, ValueType, get_default_command
-from .terminal import UserError
+from .commands import COMMANDS, OPTIONS, ArgMap, Command, Flag, HelpCommand, ValueType, get_default_command
+from .terminal import InputError
 
 
 def _resolve_pending(pending_flags: list[type[Flag]], pending_tokens: list[str]) -> ArgMap:
@@ -32,13 +32,13 @@ def _resolve_pending(pending_flags: list[type[Flag]], pending_tokens: list[str])
         if len(required) == 1:
             consumer = required[0]
         elif len(required) > 1:
-            raise UserError(f"ambiguous target for '{pending_tokens[0]}': " + ", ".join(f"-{f.char}" for f in required))
+            raise InputError(f"ambiguous target for '{pending_tokens[0]}': " + ", ".join(f"-{f.char}" for f in required))
         elif len(optional) == 1:
             consumer = optional[0]
         elif len(optional) > 1:
-            raise UserError(f"ambiguous target for '{pending_tokens[0]}': " + ", ".join(f"-{f.char}" for f in optional))
+            raise InputError(f"ambiguous target for '{pending_tokens[0]}': " + ", ".join(f"-{f.char}" for f in optional))
         else:
-            raise UserError(
+            raise InputError(
                 ", ".join(f"-{f.char}" for f in pending_flags)
                 + f" received invalid argument{('s' if len(pending_tokens) > 1 else '')}: "
                 + ", ".join(f"'{t}'" for t in pending_tokens)
@@ -49,7 +49,7 @@ def _resolve_pending(pending_flags: list[type[Flag]], pending_tokens: list[str])
             value = " ".join(pending_tokens)
         else:  # STR or INT
             if len(pending_tokens) > 1:
-                raise UserError(
+                raise InputError(
                     f"-{consumer.char} expects one token but got: " + ", ".join(f"'{t}'" for t in pending_tokens)
                 )
             value = pending_tokens[0]
@@ -57,7 +57,7 @@ def _resolve_pending(pending_flags: list[type[Flag]], pending_tokens: list[str])
                 try:
                     value = int(value)
                 except ValueError:
-                    raise UserError(f"-{consumer.char} expects an integer but got: '{pending_tokens[0]}'") from None
+                    raise InputError(f"-{consumer.char} expects an integer but got: '{pending_tokens[0]}'") from None
 
     # resolve flag values
     args: ArgMap = {}
@@ -67,7 +67,7 @@ def _resolve_pending(pending_flags: list[type[Flag]], pending_tokens: list[str])
         if f == consumer:
             args[f.char] = value
         elif f.required:
-            raise UserError(f"-{f.char} requires a value")
+            raise InputError(f"-{f.char} requires a value")
         else:
             args[f.char] = f.default
     return args
@@ -100,7 +100,7 @@ def parse(argv: list[str]) -> Command:
 
             duplicates = set(resolved.keys()) & set(args.keys())
             if duplicates:
-                raise UserError(
+                raise InputError(
                     f"duplicate flag{'' if len(duplicates) == 1 else 's'}: " + ", ".join(f"-{k}" for k in duplicates)
                 )
 
@@ -114,7 +114,7 @@ def parse(argv: list[str]) -> Command:
         if is_flag:
             for c in token[1:]:
                 if c not in flag_lookup:
-                    raise UserError(f"unknown flag: -{c}")
+                    raise InputError(f"unknown flag: -{c}")
                 pending_flags.append(flag_lookup[c])
             pos += 1
             continue
@@ -129,8 +129,10 @@ def parse(argv: list[str]) -> Command:
     valid_commands = {f.char for f in COMMANDS}
     commands = [c for c in args if c in valid_commands]
     if len(commands) > 1:
-        raise UserError("multiple commands: " + ", ".join(f"-{c}" for c in commands))
+        raise InputError("multiple commands: " + ", ".join(f"-{c}" for c in commands))
     if not commands:
-        raise UserError("no command specified")
+        if not args:
+            return HelpCommand(args)
+        raise InputError("no command specified")
 
     return flag_lookup[commands[0]](args)