weaviate-cli 3.3.0__tar.gz → 3.4.0__tar.gz

weaviate_cli-3.4.0/.claude/skills/contributing-to-weaviate-cli/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: contributing-to-weaviate-cli
+description: >-
+  Develops, tests, and reviews weaviate-cli source code. Use this skill when
+  the task involves modifying the weaviate-cli codebase itself. Trigger if
+  the request: asks to add a new command or flag to weaviate-cli; needs to
+  fix a bug in the CLI source code (weaviate_cli/ Python files); involves
+  reviewing a PR that changes weaviate-cli; wants to write or update unit or
+  integration tests for the CLI; asks about the Click-based architecture,
+  command-to-manager pattern, or defaults system; or the working directory is
+  the weaviate-cli repository and Python source files need to be modified.
+  Do NOT use for running weaviate-cli commands against a Weaviate cluster —
+  use operating-weaviate-cli for that.
+---
+
+# Contributing to weaviate-cli
+
+Guide for developing, testing, and maintaining the `weaviate-cli` codebase.
+
+## Development Setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+make install-dev          # pip install -r requirements-dev.txt + pre-commit install
+```
+
+Key development commands:
+```bash
+make format               # Black formatter on cli.py, weaviate_cli/, test/
+make lint                 # Black --check (CI-equivalent)
+make test                 # pytest test/unittests
+make build-all            # python -m build + twine check
+make all                  # format + lint + test + build-all
+```
+
+## Repository Architecture
+
+```
+weaviate-cli/
+  cli.py                        # Entry point: Click group, global options, command registration
+  weaviate_cli/
+    __init__.py                 # Package version
+    defaults.py                 # Dataclass defaults for all commands
+    utils.py                    # Shared helpers: get_client, pp_objects, parse_permission
+    commands/                   # Click command definitions (one file per group)
+      create.py                 # create collection, tenants, data, backup, role, user, alias, replication
+      get.py                    # get collection, tenants, shards, backup, role, user, nodes, alias, replication
+      update.py                 # update collection, tenants, shards, data, user, alias
+      delete.py                 # delete collection, tenants, data, role, user, alias, replication
+      query.py                  # query data, replications, sharding-state
+      restore.py                # restore backup
+      cancel.py                 # cancel backup, replication
+      assign.py                 # assign role, permission
+      revoke.py                 # revoke role, permission
+      benchmark.py              # benchmark qps
+    managers/                   # Business logic (one file per domain)
+      config_manager.py         # ConfigManager: config loading, client creation
+      collection_manager.py     # CollectionManager: CRUD collections
+      tenant_manager.py         # TenantManager: CRUD tenants
+      data_manager.py           # DataManager: ingest/update/delete data
+      backup_manager.py         # BackupManager: backup/restore operations
+      role_manager.py           # RoleManager: RBAC role operations
+      user_manager.py           # UserManager: RBAC user operations
+      node_manager.py           # NodeManager: node information
+      shard_manager.py          # ShardManager: shard operations
+      cluster_manager.py        # ClusterManager: replication operations
+      alias_manager.py          # AliasManager: alias operations
+      benchmark_manager.py      # BenchmarkManager: QPS benchmarks
+    completion/                 # Shell completion helpers
+    datasets/                   # Built-in datasets (Movies)
+    types/                      # Type definitions
+  test/
+    unittests/
+      conftest.py               # Fixtures: mock_client, mock_config, mock_click_context
+      test_cli.py               # CliRunner tests for CLI entry point
+      test_defaults.py          # Defaults dataclass tests
+      test_utils.py             # Utility function tests
+      test_managers/             # Manager unit tests (one per manager)
+    integration/
+      test_integration.py       # Integration tests (requires running cluster)
+      test_auth_integration.py  # RBAC integration tests (requires cluster + RBAC)
+      test_data_integration.py  # Data integration tests
+```
+
+See [references/architecture.md](references/architecture.md) for detailed class hierarchy and patterns.
+
+## Architecture Pattern: Commands -> Managers
+
+Every CLI operation follows this pattern:
+
+1. **`cli.py`**: Top-level Click group registers command groups
+2. **`commands/<group>.py`**: Click decorators define options, validate input, get client from context, call manager
+3. **`managers/<domain>_manager.py`**: Business logic, Weaviate client calls, output formatting
+4. **`defaults.py`**: Dataclass with default values for each command
+
+```
+cli.py (main group)
+  -> commands/create.py (create group)
+    -> @create.command("collection") (Click decorators + options)
+      -> CollectionManager(client).create_collection(...) (business logic)
+        -> defaults.py::CreateCollectionDefaults (default values)
+```
+
+The `ConfigManager` is stored in the Click context (`ctx.obj["config"]`). Commands extract the client via `get_client_from_context(ctx)` from `utils.py`.
+
+## Defaults System
+
+All command defaults live in `weaviate_cli/defaults.py` as dataclasses:
+
+```python
+@dataclass
+class CreateCollectionDefaults:
+    collection: str = "Movies"
+    replication_factor: int = 3
+    vector_index: str = "hnsw"
+    multitenant: bool = False
+    # ... etc
+```
+
+Click options reference these: `default=CreateCollectionDefaults.collection`. This keeps defaults centralized and testable.
+
+When adding a new command, always create a corresponding defaults dataclass.
+
+## Issue Tracking
+
+By default, every non-trivial task (new feature, bug fix, improvement) should follow the
+GitHub Issue workflow defined in `references/issue-workflow.md` (including any documented
+exceptions, such as documentation-only or agent/Claude-specific changes). This provides:
+- A record of what was added in each release
+- A link between issues and PRs for code review
+- Visibility into work in progress
+
+**Default workflow for non-trivial changes:**
+1. Create issue with `draft` label via `gh issue create --repo weaviate/weaviate-cli`
+2. Plan and implement the change
+3. Create a PR with `Closes #N` in the body
+4. Remove `draft` label when PR is ready for review
+
+See [references/issue-workflow.md](references/issue-workflow.md) for full details,
+templates, examples, and the authoritative list of exceptions. If this section ever
+conflicts with that reference, defer to `references/issue-workflow.md`.
+
+## Adding a New Command
+
+Step-by-step guide: see [references/adding-commands.md](references/adding-commands.md).
+
+Summary:
+1. Create a GitHub Issue to track the work (see Issue Tracking above)
+2. Add a defaults dataclass in `defaults.py`
+3. Add Click command in the appropriate `commands/<group>.py`
+4. Add manager method in `managers/<domain>_manager.py`
+5. Add `--json` flag (mandatory for all commands)
+6. Add unit test in `test/unittests/test_managers/`
+7. Update the operating skill documentation
+8. Create a PR linked to the issue
+
+## JSON Output Convention
+
+Every command **must** support `--json`:
+
+**In the Click command:**
+```python
+@click.option("--json", "json_output", is_flag=True, default=False, help="Output in JSON format.")
+```
+
+Note: The parameter is named `json_output` (not `json`) to avoid shadowing Python's `json` module.
+
+**In the manager**, use `print_json_or_text()` from `utils.py`:
+```python
+from weaviate_cli.utils import print_json_or_text
+
+print_json_or_text(
+    data={"collections": collection_list, "total": len(collection_list)},
+    json_output=json_output,
+    text_fn=lambda: click.echo(formatted_text),
+)
+```
+
+**Success JSON shape:**
+```json
+{"status": "success", "message": "..."}
+```
+or structured data with domain-specific fields.
+
+**Error output:** Always `click.echo(f"Error: {e}")` + `sys.exit(1)`.
+
+## Testing
+
+### Unit Tests
+
+Use `CliRunner` for CLI-level tests and `MagicMock` for manager tests:
+
+```python
+# CLI test (test/unittests/test_cli.py)
+from click.testing import CliRunner
+from cli import main
+
+def test_create_collection(cli_runner):
+    result = cli_runner.invoke(main, ["create", "collection", "--json"])
+    assert result.exit_code == 0
+
+# Manager test (test/unittests/test_managers/test_collection_manager.py)
+def test_create_collection(mock_client):
+    mock_client.collections.exists.side_effect = [False, True]
+    manager = CollectionManager(mock_client)
+    manager.create_collection(collection="Test", replication_factor=3)
+    mock_client.collections.create.assert_called_once()
+```
+
+Fixtures in `conftest.py` (shared across all unit tests):
+- `mock_client` -- `MagicMock(spec=weaviate.WeaviateClient)`
+- `mock_config` -- `MagicMock(spec=ConfigManager)`
+- `mock_click_context` -- context with mock config in `ctx.obj`
+
+Note: `cli_runner` is defined locally in `test/unittests/test_cli.py`, not in `conftest.py`.
+
+### Integration Tests
+
+Require a running Weaviate cluster (typically via `weaviate-local-k8s`):
+```bash
+pytest test/integration/test_integration.py
+pytest test/integration/test_auth_integration.py  # Requires RBAC-enabled cluster
+```
+
+See [references/testing.md](references/testing.md) for full patterns.
+
+## CI Pipeline
+
+```
+lint-and-format (Black + build check)
+  -> unit-tests (Python 3.9-3.13, matrix)
+    -> integration-tests (latest Weaviate, weaviate-local-k8s, Python 3.9-3.13)
+    -> integration-auth-tests (RBAC-enabled cluster, Python 3.9-3.13)
+```
+
+- Linting must pass before unit tests run
+- Unit tests must pass before integration tests run
+- Integration tests use `weaviate/weaviate-local-k8s@v2` GitHub Action
+- Auth integration tests create a config with `admin-key` API key
+
+## Code Review Checklist
+
+1. GitHub Issue exists and is linked to the PR (`Closes #N`)
+2. New command has `--json` support
+3. Defaults dataclass added/updated in `defaults.py`
+4. Unit test covers happy path and error cases
+5. Black formatting passes (`make lint`)
+6. No hardcoded paths or credentials
+7. Error messages follow `Error: <description>` pattern
+8. Client is properly closed in `finally` block
+9. Manager method handles both JSON and text output
+
+See [references/code-review.md](references/code-review.md) for detailed checklist.
+
+## Maintaining Skills
+
+When adding new commands or options to `weaviate-cli`, update the agent skills:
+
+1. **Operating skill** (`.claude/skills/operating-weaviate-cli/`):
+   - Add the new command to the **Command Reference** section in `SKILL.md`
+   - Update or create the relevant reference file in `references/`
+   - Update the **Command Groups** table if a new group is added
+   - Update **Workflow Dependencies** if the command introduces new dependencies
+
+2. **Contributing skill** (`.claude/skills/contributing-to-weaviate-cli/`):
+   - Update `references/architecture.md` if new files/modules are added
+   - Update `references/adding-commands.md` if patterns change
+   - Update `references/testing.md` if test infrastructure changes
+
+3. **CLAUDE.md**: Update if development commands or conventions change
+
+## References
+
+- [references/architecture.md](references/architecture.md) -- File-by-file breakdown, class hierarchy, utils helpers
+- [references/adding-commands.md](references/adding-commands.md) -- Complete worked example for new commands
+- [references/testing.md](references/testing.md) -- Test fixtures, patterns, CI details
+- [references/code-review.md](references/code-review.md) -- PR checklist, common pitfalls, conventions
+- [references/issue-workflow.md](references/issue-workflow.md) -- GitHub Issue creation, tracking, and PR linking

weaviate_cli-3.4.0/.claude/skills/contributing-to-weaviate-cli/references/adding-commands.md

@@ -0,0 +1,215 @@
+# Adding Commands Reference
+
+Complete worked example for adding a new command to weaviate-cli.
+
+## Step 1: Add Defaults Dataclass
+
+In `weaviate_cli/defaults.py`, add a dataclass with default values:
+
+```python
+@dataclass
+class CreateWidgetDefaults:
+    collection: str = "Movies"
+    widget_name: str = "default-widget"
+    size: int = 100
+    enabled: bool = False
+```
+
+## Step 2: Add Click Command
+
+In the appropriate `weaviate_cli/commands/<group>.py` file, add the command:
+
+```python
+from weaviate_cli.defaults import CreateWidgetDefaults
+
+@create.command("widget")
+@click.option(
+    "--collection",
+    default=CreateWidgetDefaults.collection,
+    help="The collection to create the widget in.",
+    shell_complete=collection_name_complete,
+)
+@click.option(
+    "--widget_name",
+    default=CreateWidgetDefaults.widget_name,
+    help="Name of the widget.",
+)
+@click.option(
+    "--size",
+    default=CreateWidgetDefaults.size,
+    help=f"Widget size (default: {CreateWidgetDefaults.size}).",
+    type=int,
+)
+@click.option(
+    "--enabled",
+    is_flag=True,
+    help="Enable the widget (default: False).",
+)
+@click.option(
+    "--json", "json_output", is_flag=True, default=False, help="Output in JSON format."
+)
+@click.pass_context
+def create_widget_cli(ctx, collection, widget_name, size, enabled, json_output):
+    """Create a widget in Weaviate."""
+    client = None
+    try:
+        client = get_client_from_context(ctx)
+        manager = WidgetManager(client)
+        manager.create_widget(
+            collection=collection,
+            widget_name=widget_name,
+            size=size,
+            enabled=enabled,
+            json_output=json_output,
+        )
+    except Exception as e:
+        click.echo(f"Error: {e}")
+        if client:
+            client.close()
+        sys.exit(1)
+    finally:
+        if client:
+            client.close()
+```
+
+### Key patterns to follow:
+
+- **Parameter naming:** `--json` is aliased to `json_output` to avoid shadowing Python's `json` module
+- **Default references:** Always use `CreateWidgetDefaults.field_name`, never hardcode defaults
+- **Client lifecycle:** Get client in try, close in finally, echo error and exit(1) in except
+- **Shell completion:** Use `shell_complete=collection_name_complete` for collection options
+- **Boolean flags:** Use `is_flag=True` for boolean options
+- **Choice options:** Use `type=click.Choice([...])` for constrained values
+- **Help text:** Include default value in help string
+
+## Step 3: Add Manager
+
+Create `weaviate_cli/managers/widget_manager.py` (or add to an existing manager):
+
+```python
+import click
+import json
+from weaviate import WeaviateClient
+from weaviate_cli.utils import print_json_or_text
+
+
+class WidgetManager:
+    def __init__(self, client: WeaviateClient):
+        self.client = client
+
+    def create_widget(
+        self,
+        collection: str,
+        widget_name: str,
+        size: int,
+        enabled: bool,
+        json_output: bool = False,
+    ):
+        # Validation
+        if not self.client.collections.exists(collection):
+            raise Exception(f"Collection '{collection}' does not exist.")
+
+        # Business logic
+        result = self.client.collections.get(collection).do_something(
+            name=widget_name, size=size, enabled=enabled
+        )
+
+        # Output
+        data = {
+            "status": "success",
+            "message": f"Widget '{widget_name}' created in collection '{collection}'.",
+            "widget": {"name": widget_name, "size": size, "enabled": enabled},
+        }
+        print_json_or_text(
+            data=data,
+            json_output=json_output,
+            text_fn=lambda: click.echo(
+                f"Widget '{widget_name}' created successfully in '{collection}'."
+            ),
+        )
+```
+
+### Manager patterns:
+
+- Raise exceptions with descriptive messages (caught by command's except block)
+- Use `print_json_or_text()` for dual output support
+- Accept `json_output: bool = False` parameter
+- Don't call `sys.exit()` from managers -- let the command handle it
+
+## Step 4: Add Unit Test
+
+Create `test/unittests/test_managers/test_widget_manager.py`:
+
+```python
+import pytest
+from unittest.mock import MagicMock
+from weaviate_cli.managers.widget_manager import WidgetManager
+
+
+def test_create_widget(mock_client):
+    # Setup mock chain
+    mock_collections = MagicMock()
+    mock_client.collections = mock_collections
+    mock_collections.exists.return_value = True
+    mock_collection = MagicMock()
+    mock_collections.get.return_value = mock_collection
+
+    manager = WidgetManager(mock_client)
+    manager.create_widget(
+        collection="TestCollection",
+        widget_name="test-widget",
+        size=50,
+        enabled=True,
+    )
+
+    mock_collections.exists.assert_called_once_with("TestCollection")
+    mock_collections.get.assert_called_once_with("TestCollection")
+
+
+def test_create_widget_collection_not_found(mock_client):
+    mock_client.collections.exists.return_value = False
+    manager = WidgetManager(mock_client)
+
+    with pytest.raises(Exception) as exc_info:
+        manager.create_widget(
+            collection="NonExistent",
+            widget_name="test-widget",
+            size=50,
+        )
+
+    assert "does not exist" in str(exc_info.value)
+```
+
+### Test patterns:
+
+- Use `mock_client` fixture from `conftest.py`
+- Test happy path: verify correct calls were made
+- Test error path: verify exception raised with correct message
+- Mock chains: `mock_client.collections.get.return_value = mock_collection`
+
+## Step 5: Add Import
+
+If you created a new manager, import it in the command file:
+
+```python
+from weaviate_cli.managers.widget_manager import WidgetManager
+```
+
+## Step 6: Update Documentation
+
+1. Add the command to `.claude/skills/operating-weaviate-cli/SKILL.md` command reference
+2. Update or create the relevant reference file in `.claude/skills/operating-weaviate-cli/references/`
+3. Update `CLAUDE.md` if the command introduces new patterns
+
+## Checklist
+
+- [ ] GitHub Issue created on `weaviate/weaviate-cli` with `draft` label
+- [ ] Defaults dataclass in `defaults.py`
+- [ ] Click command with `--json` support
+- [ ] Manager with `print_json_or_text()` output
+- [ ] Unit test (happy path + error path)
+- [ ] Import in command file
+- [ ] Black formatting passes (`make format && make lint`)
+- [ ] Skill documentation updated
+- [ ] PR created with `Closes #N` linking to the issue
+- [ ] `draft` label removed from issue

weaviate_cli-3.4.0/.claude/skills/contributing-to-weaviate-cli/references/architecture.md

@@ -0,0 +1,146 @@
+# Architecture Reference
+
+Detailed breakdown of the weaviate-cli codebase structure and patterns.
+
+## Entry Point: `cli.py`
+
+The CLI entry point defines the top-level Click group with global options (`--config-file`, `--user`, `--version`) and registers all command groups:
+
+```python
+@click.group()
+@click.option("--config-file", ...)
+@click.option("--user", ...)
+@click.option("--version", is_flag=True, callback=print_version, is_eager=True, ...)
+@click.pass_context
+def main(ctx, config_file, user):
+    try:
+        ctx.obj = {"config": ConfigManager(config_file, user)}
+    except Exception as e:
+        click.echo(f"Fatal Error: {e}")
+        sys.exit(1)
+
+main.add_command(create)
+main.add_command(delete)
+# ... etc
+```
+
+Key points:
+- `ConfigManager` is created once and stored in `ctx.obj["config"]`
+- Config creation is wrapped in try/except -- uses `"Fatal Error:"` prefix (distinct from the `"Error:"` prefix used in commands)
+- Commands extract the client via `get_client_from_context(ctx)` from `utils.py`
+- The `--version` flag uses an eager callback to print and exit
+
+## Command Files: `weaviate_cli/commands/`
+
+Each file defines a Click group and its subcommands. Pattern:
+
+```python
+@click.group()
+def create():
+    """Create resources in Weaviate."""
+    pass
+
+@create.command("collection")
+@click.option("--collection", default=CreateCollectionDefaults.collection, ...)
+@click.option("--json", "json_output", is_flag=True, default=False, ...)
+@click.pass_context
+def create_collection_cli(ctx, collection, ..., json_output):
+    client = None
+    try:
+        client = get_client_from_context(ctx)
+        manager = CollectionManager(client)
+        manager.create_collection(collection=collection, ...)
+    except Exception as e:
+        click.echo(f"Error: {e}")
+        if client:
+            client.close()
+        sys.exit(1)
+    finally:
+        if client:
+            client.close()
+```
+
+Every command follows this structure:
+1. Click decorators with options referencing defaults
+2. `json_output` parameter (aliased from `--json`)
+3. Try/except/finally with client cleanup
+4. Delegate to manager for business logic
+
+## Manager Files: `weaviate_cli/managers/`
+
+Managers encapsulate business logic. Each takes a `WeaviateClient` in `__init__`:
+
+```python
+class CollectionManager:
+    def __init__(self, client: WeaviateClient):
+        self.client = client
+
+    def create_collection(self, collection, replication_factor, ...):
+        if self.client.collections.exists(collection):
+            raise Exception(f"Error: Collection '{collection}' already exists...")
+        self.client.collections.create(name=collection, ...)
+```
+
+Managers handle:
+- Input validation and error messages
+- Weaviate client API calls
+- Output formatting (JSON vs text via `print_json_or_text`)
+
+## ConfigManager: `weaviate_cli/managers/config_manager.py`
+
+Handles configuration loading and client creation:
+
+- Default config path: `~/.config/weaviate/config.json`
+- If no config file exists and none specified, creates default (localhost) config
+- Supports three connection modes: local, Weaviate Cloud, custom host
+- `get_client()` returns sync client, `get_async_client()` returns async client
+- Handles `SLOW_CONNECTION` env var for doubled timeouts
+- For `auth.type == "user"`, requires `--user` flag to select API key
+
+## Defaults: `weaviate_cli/defaults.py`
+
+Centralized defaults as dataclasses. One dataclass per command:
+
+```python
+@dataclass
+class CreateCollectionDefaults:
+    collection: str = "Movies"
+    replication_factor: int = 3
+    vector_index: str = "hnsw"
+    # ...
+```
+
+Also contains:
+- `PERMISSION_HELP_STRING` -- Multi-line help text for `-p` flag
+- `QUERY_MAXIMUM_RESULTS` -- Hard limit for query results
+- `MAX_OBJECTS_PER_BATCH` -- Batch size cap
+- `MAX_WORKERS` -- Computed from CPU count (capped at 32)
+
+## Utils: `weaviate_cli/utils.py`
+
+Shared utility functions:
+
+| Function | Purpose |
+|----------|---------|
+| `get_client_from_context(ctx)` | Extract sync client from Click context |
+| `get_async_client_from_context(ctx)` | Extract async client from Click context |
+| `print_json_or_text(data, json_output, text_fn)` | Output JSON or formatted text |
+| `pp_objects(response, properties, json_output)` | Pretty-print query results |
+| `parse_permission(perm)` | Parse permission string to RBAC objects |
+| `older_than_version(client, version)` | Check if Weaviate server is older than given version |
+| `is_version_older_than(version, check_version)` | Compare two semver strings |
+| `get_random_string(length)` | Random string generator |
+
+## Completion: `weaviate_cli/completion/`
+
+Shell completion helpers for Click options:
+- `collection_name_complete` -- Auto-complete collection names
+- `role_name_complete` -- Auto-complete role names
+
+## Types: `weaviate_cli/types/`
+
+Type definitions used across the codebase.
+
+## Datasets: `weaviate_cli/datasets/`
+
+Built-in datasets (Movies) used for non-randomized data ingestion.