maybeai-sheet-cli 0.1.0__py3-none-any.whl

maybeai_sheet/__init__.py

@@ -0,0 +1,5 @@
+"""MaybeAI Sheet CLI package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

maybeai_sheet/cli.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import typer
+
+from .commands.raw import app as raw_app
+from .commands.sheet import app as sheet_app
+from .commands.workbook import app as workbook_app
+from .config import CLIContext
+from .formatters import handle_cli_error
+
+app = typer.Typer(
+    help="CLI for common MaybeAI spreadsheet operations.",
+    no_args_is_help=True,
+    rich_markup_mode="markdown",
+)
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    from . import __version__
+
+    typer.echo(__version__)
+    raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    token: Optional[str] = typer.Option(
+        None,
+        "--token",
+        envvar="MAYBEAI_API_TOKEN",
+        help="MaybeAI API token. Defaults to MAYBEAI_API_TOKEN.",
+    ),
+    base_url: str = typer.Option(
+        "https://play-be.omnimcp.ai",
+        "--base-url",
+        help="MaybeAI API base URL.",
+    ),
+    doc_id: Optional[str] = typer.Option(
+        None,
+        "--doc-id",
+        help="MaybeAI document ID.",
+    ),
+    url: Optional[str] = typer.Option(
+        None,
+        "--url",
+        help="MaybeAI workbook URL. The CLI will parse document_id and gid when possible.",
+    ),
+    uri: Optional[str] = typer.Option(
+        None,
+        "--uri",
+        help="Fully resolved MaybeAI workbook URI.",
+    ),
+    gid: Optional[int] = typer.Option(
+        None,
+        "--gid",
+        help="Worksheet gid.",
+    ),
+    worksheet_name: Optional[str] = typer.Option(
+        None,
+        "--worksheet-name",
+        help="Worksheet name. Prefer this when the endpoint supports it.",
+    ),
+    output: str = typer.Option(
+        "json",
+        "--output",
+        help="Output format: json, table, yaml.",
+    ),
+    timeout: float = typer.Option(
+        30.0,
+        "--timeout",
+        min=1.0,
+        help="HTTP timeout in seconds.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        help="Show extra resolution details.",
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    del version
+    try:
+        ctx.obj = CLIContext(
+            token=token or os.getenv("MAYBEAI_API_TOKEN"),
+            base_url=base_url,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=gid,
+            worksheet_name=worksheet_name,
+            output=output,  # type: ignore[arg-type]
+            timeout=timeout,
+            verbose=verbose,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
+app.add_typer(workbook_app, name="workbook")
+app.add_typer(sheet_app, name="sheet")
+app.add_typer(raw_app, name="raw")
+
+
+if __name__ == "__main__":
+    app()

maybeai_sheet/client.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .config import CLIContext
+from .errors import APIRequestError, UsageError
+
+
+class MaybeAIClient:
+    def __init__(self, state: CLIContext) -> None:
+        if not state.token:
+            raise UsageError("Missing MaybeAI token. Set --token or MAYBEAI_API_TOKEN.")
+        self.state = state
+
+    def _headers(self, *, content_type: bool = True) -> dict[str, str]:
+        headers = {"Authorization": f"Bearer {self.state.token}"}
+        if content_type:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    def _endpoint(self, path: str) -> str:
+        base = self.state.base_url.rstrip("/")
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        if not path.startswith("/"):
+            path = f"/{path}"
+        return f"{base}{path}"
+
+    def _raise_for_error(self, response: httpx.Response, *, endpoint: str) -> None:
+        if response.status_code < 400:
+            return
+        try:
+            body: object = response.json()
+        except json.JSONDecodeError:
+            body = response.text
+        raise APIRequestError(
+            f"Request failed with status {response.status_code}",
+            status_code=response.status_code,
+            endpoint=endpoint,
+            body=body,
+        )
+
+    def post_json(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        endpoint = self._endpoint(path)
+        with httpx.Client(timeout=self.state.timeout, trust_env=False) as client:
+            response = client.post(endpoint, json=payload, headers=self._headers())
+        self._raise_for_error(response, endpoint=endpoint)
+        return response.json()
+
+    def get_bytes(self, path: str) -> bytes:
+        endpoint = self._endpoint(path)
+        with httpx.Client(timeout=self.state.timeout, trust_env=False) as client:
+            response = client.get(endpoint, headers=self._headers(content_type=False))
+        self._raise_for_error(response, endpoint=endpoint)
+        return response.content
+
+    def upload_file(self, path: str, file_path: Path, *, user_id: str | None = None) -> dict[str, Any]:
+        endpoint = self._endpoint(path)
+        files = {"file": (file_path.name, file_path.open("rb"))}
+        data: dict[str, str] = {}
+        if user_id:
+            data["user_id"] = user_id
+        try:
+            with httpx.Client(timeout=self.state.timeout, trust_env=False) as client:
+                response = client.post(
+                    endpoint,
+                    headers=self._headers(content_type=False),
+                    files=files,
+                    data=data,
+                )
+        finally:
+            files["file"][1].close()
+        self._raise_for_error(response, endpoint=endpoint)
+        return response.json()

maybeai_sheet/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command groups for MaybeAI Sheet."""

maybeai_sheet/commands/raw.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ..client import MaybeAIClient
+from ..config import CLIContext
+from ..formatters import build_command_output, handle_cli_error, load_json_file, render_output
+
+app = typer.Typer(help="Low-level API escape hatch.", no_args_is_help=True)
+
+
+@app.command("post")
+def post(
+    ctx: typer.Context,
+    path: str = typer.Argument(..., help="API path, for example /api/v1/excel/read_sheet."),
+    body: Optional[Path] = typer.Option(
+        None,
+        "--body",
+        exists=True,
+        readable=True,
+        resolve_path=True,
+        help="Optional JSON request body.",
+    ),
+) -> None:
+    try:
+        state: CLIContext = ctx.obj
+        client = MaybeAIClient(state)
+        payload = load_json_file(body) if body else {}
+        response = client.post_json(path, payload)
+        render_output(build_command_output(endpoint=path, result=response), state.output)
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)

maybeai_sheet/commands/sheet.py

@@ -0,0 +1,440 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ..client import MaybeAIClient
+from ..config import CLIContext
+from ..formatters import build_command_output, handle_cli_error, load_json_file, render_output
+from ..models.sheet import (
+    AppendRowsRequest,
+    CreateWorksheetRequest,
+    ListWorksheetsRequest,
+    ReadHeadersRequest,
+    ReadSheetRequest,
+    UpdateRangeRequest,
+    UpsertRowsRequest,
+)
+from ..resolver import resolve_target
+
+app = typer.Typer(help="Worksheet read/write operations.", no_args_is_help=True)
+
+
+def _state_with_target_overrides(
+    state: CLIContext,
+    *,
+    doc_id: str | None,
+    url: str | None,
+    uri: str | None,
+    gid: int | None,
+    worksheet_name: str | None,
+) -> CLIContext:
+    return CLIContext(
+        token=state.token,
+        base_url=state.base_url,
+        doc_id=doc_id or state.doc_id,
+        url=url or state.url,
+        uri=uri or state.uri,
+        gid=gid if gid is not None else state.gid,
+        worksheet_name=worksheet_name or state.worksheet_name,
+        output=state.output,
+        timeout=state.timeout,
+        verbose=state.verbose,
+    )
+
+
+def _read_verify(
+    client: MaybeAIClient,
+    *,
+    endpoint: str,
+    uri: str,
+    worksheet_name: str | None,
+    cell_range: str | None = None,
+) -> dict[str, object]:
+    payload = ReadSheetRequest(
+        uri=uri,
+        worksheet_name=worksheet_name,
+        range_address=cell_range,
+    )
+    return client.post_json(endpoint, payload.model_dump(exclude_none=True))
+
+
+@app.command("read")
+def read_sheet(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
+    worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Worksheet name."),
+    cell_range: Optional[str] = typer.Option(None, "--range", help="Optional A1-style range."),
+    value_render_option: Optional[str] = typer.Option(
+        None,
+        "--value-render-option",
+        help="Optional MaybeAI render option such as FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA.",
+    ),
+) -> None:
+    try:
+        state: CLIContext = _state_with_target_overrides(
+            ctx.obj,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=gid,
+            worksheet_name=worksheet_name,
+        )
+        client = MaybeAIClient(state)
+        target = resolve_target(
+            state,
+            force_gid_uri=bool(state.gid is not None and not state.worksheet_name),
+        )
+        payload = ReadSheetRequest(
+            uri=target.uri,
+            worksheet_name=target.worksheet_name,
+            range_address=cell_range,
+            value_render_option=value_render_option,
+        )
+        endpoint = "/api/v1/excel/read_sheet"
+        response = client.post_json(endpoint, payload.model_dump(exclude_none=True))
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
+@app.command("read-range")
+def read_range(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
+    worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Worksheet name."),
+    cell_range: str = typer.Option(..., "--range", help="A1-style range to read."),
+) -> None:
+    read_sheet(
+        ctx,
+        doc_id=doc_id,
+        url=url,
+        uri=uri,
+        gid=gid,
+        worksheet_name=worksheet_name,
+        cell_range=cell_range,
+    )
+
+
+@app.command("headers")
+def headers(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
+    worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Worksheet name."),
+) -> None:
+    try:
+        state: CLIContext = _state_with_target_overrides(
+            ctx.obj,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=gid,
+            worksheet_name=worksheet_name,
+        )
+        client = MaybeAIClient(state)
+        target = resolve_target(state, force_gid_uri=True)
+        payload = ReadHeadersRequest(uri=target.uri)
+        endpoint = "/api/v1/excel/read_headers"
+        response = client.post_json(endpoint, payload.model_dump())
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
+@app.command("worksheets")
+def worksheets(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+) -> None:
+    try:
+        state: CLIContext = _state_with_target_overrides(
+            ctx.obj,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=None,
+            worksheet_name=None,
+        )
+        client = MaybeAIClient(state)
+        target = resolve_target(state)
+        payload = ListWorksheetsRequest(uri=target.uri)
+        endpoint = "/api/v1/excel/list_worksheets"
+        response = client.post_json(endpoint, payload.model_dump())
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
+@app.command("formulas")
+def formulas(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
+    worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Worksheet name."),
+    cell_range: Optional[str] = typer.Option(None, "--range", help="Optional A1-style range."),
+) -> None:
+    read_sheet(
+        ctx,
+        doc_id=doc_id,
+        url=url,
+        uri=uri,
+        gid=gid,
+        worksheet_name=worksheet_name,
+        cell_range=cell_range,
+        value_render_option="FORMULA",
+    )
+
+
+@app.command("write-range")
+def write_range(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
+    worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Worksheet name."),
+    cell_range: str = typer.Option(..., "--range", help="A1-style range to write."),
+    values: Path = typer.Option(
+        ...,
+        "--values",
+        exists=True,
+        readable=True,
+        resolve_path=True,
+        help="Path to JSON values payload.",
+    ),
+    verify: bool = typer.Option(False, "--verify", help="Read back after write."),
+) -> None:
+    try:
+        state: CLIContext = _state_with_target_overrides(
+            ctx.obj,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=gid,
+            worksheet_name=worksheet_name,
+        )
+        client = MaybeAIClient(state)
+        target = resolve_target(state)
+        payload = UpdateRangeRequest(
+            uri=target.uri,
+            worksheet_name=target.worksheet_name,
+            range_address=cell_range,
+            values=load_json_file(values),
+        )
+        endpoint = "/api/v1/excel/update_range"
+        response = client.post_json(endpoint, payload.model_dump(exclude_none=True))
+        if verify:
+            verify_result = _read_verify(
+                client,
+                endpoint="/api/v1/excel/read_sheet",
+                uri=target.uri,
+                worksheet_name=target.worksheet_name,
+                cell_range=cell_range,
+            )
+            render_output(
+                build_command_output(
+                    endpoint=endpoint,
+                    target=target,
+                    result=response,
+                    verify=verify_result,
+                ),
+                state.output,
+            )
+            return
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
+@app.command("append")
+def append_rows(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
+    worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Worksheet name."),
+    rows: Path = typer.Option(
+        ...,
+        "--rows",
+        exists=True,
+        readable=True,
+        resolve_path=True,
+        help="Path to JSON rows payload.",
+    ),
+    verify: bool = typer.Option(False, "--verify", help="Read back after write."),
+) -> None:
+    try:
+        state: CLIContext = _state_with_target_overrides(
+            ctx.obj,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=gid,
+            worksheet_name=worksheet_name,
+        )
+        client = MaybeAIClient(state)
+        target = resolve_target(state, force_gid_uri=True)
+        payload = AppendRowsRequest(
+            uri=target.uri,
+            worksheet_name=target.worksheet_name,
+            data=load_json_file(rows),
+        )
+        endpoint = "/api/v1/excel/append_rows"
+        response = client.post_json(endpoint, payload.model_dump(exclude_none=True))
+        if verify:
+            verify_result = _read_verify(
+                client,
+                endpoint="/api/v1/excel/read_sheet",
+                uri=target.uri,
+                worksheet_name=target.worksheet_name,
+            )
+            render_output(
+                build_command_output(
+                    endpoint=endpoint,
+                    target=target,
+                    result=response,
+                    verify=verify_result,
+                ),
+                state.output,
+            )
+            return
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
+@app.command("upsert")
+def upsert_rows(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
+    worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Worksheet name."),
+    key: str = typer.Option(..., "--key", help="Business key column."),
+    rows: Path = typer.Option(
+        ...,
+        "--rows",
+        exists=True,
+        readable=True,
+        resolve_path=True,
+        help="Path to JSON rows payload.",
+    ),
+    verify: bool = typer.Option(False, "--verify", help="Read back after write."),
+) -> None:
+    try:
+        state: CLIContext = _state_with_target_overrides(
+            ctx.obj,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=gid,
+            worksheet_name=worksheet_name,
+        )
+        client = MaybeAIClient(state)
+        target = resolve_target(state, force_gid_uri=True)
+        payload = UpsertRowsRequest(
+            uri=target.uri,
+            data=load_json_file(rows),
+            on=[key],
+            override=False,
+            skip_recalculation=False,
+        )
+        endpoint = "/api/v1/excel/update_range_by_lookup"
+        response = client.post_json(endpoint, payload.model_dump(exclude_none=True))
+        if verify:
+            verify_result = _read_verify(
+                client,
+                endpoint="/api/v1/excel/read_sheet",
+                uri=target.uri,
+                worksheet_name=target.worksheet_name,
+            )
+            render_output(
+                build_command_output(
+                    endpoint=endpoint,
+                    target=target,
+                    result=response,
+                    verify=verify_result,
+                ),
+                state.output,
+            )
+            return
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
+@app.command("create-worksheet")
+def create_worksheet(
+    ctx: typer.Context,
+    doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    name: str = typer.Option(..., "--name", help="Worksheet name to create."),
+    values: Optional[Path] = typer.Option(
+        None,
+        "--values",
+        exists=True,
+        readable=True,
+        resolve_path=True,
+        help="Optional path to starter JSON values payload.",
+    ),
+) -> None:
+    try:
+        state: CLIContext = _state_with_target_overrides(
+            ctx.obj,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            gid=None,
+            worksheet_name=None,
+        )
+        client = MaybeAIClient(state)
+        target = resolve_target(state)
+        payload = CreateWorksheetRequest(
+            uri=target.uri,
+            worksheet_name=name,
+            values=load_json_file(values) if values is not None else None,
+        )
+        endpoint = "/api/v1/excel/write_new_worksheet"
+        response = client.post_json(endpoint, payload.model_dump(exclude_none=True))
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)

maybeai_sheet/commands/workbook.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ..client import MaybeAIClient
+from ..config import CLIContext
+from ..formatters import build_command_output, handle_cli_error, load_json_file, render_output
+from ..models.workbook import CreateWorkbookRequest
+from ..resolver import ResolvedTarget, parse_document_target
+
+app = typer.Typer(help="Workbook-level operations.", no_args_is_help=True)
+
+
+@app.command("create")
+def create_workbook(
+    ctx: typer.Context,
+    title: str = typer.Option(..., "--title", help="Workbook title."),
+    data: Optional[Path] = typer.Option(
+        None,
+        "--data",
+        exists=True,
+        readable=True,
+        resolve_path=True,
+        help="Optional JSON file containing a list of row objects.",
+    ),
+    sheet_name: Optional[str] = typer.Option(
+        None,
+        "--sheet-name",
+        help="Optional initial worksheet name.",
+    ),
+    column_order: Optional[str] = typer.Option(
+        None,
+        "--column-order",
+        help="Comma-separated explicit column order for row-object data.",
+    ),
+) -> None:
+    try:
+        state: CLIContext = ctx.obj
+        client = MaybeAIClient(state)
+        rows = load_json_file(data) if data else [{}]
+        payload = CreateWorkbookRequest(
+            sheet_name=sheet_name or "Sheet1",
+            filename=f"{title}.xlsx",
+            data=rows,
+        )
+        if column_order:
+            payload = payload.model_copy(
+                update={
+                    "column_order": [part.strip() for part in column_order.split(",") if part.strip()]
+                }
+            )
+        endpoint = "/api/v1/excel/write_new_sheet"
+        response = client.post_json(endpoint, payload.model_dump(exclude_none=True))
+        spreadsheet_url = str(response.get("spreadsheet_url") or "")
+        response_doc_id = str(
+            response.get("spreadsheet_id") or response.get("document_id") or ""
+        ) or None
+        _, response_gid = parse_document_target(spreadsheet_url)
+        target = ResolvedTarget(
+            document_id=response_doc_id,
+            url=spreadsheet_url or None,
+            uri=spreadsheet_url or "",
+            gid=response_gid,
+            worksheet_name=sheet_name or "Sheet1",
+        )
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)
+
+
+@app.command("create-from-file")
+def create_from_file(
+    ctx: typer.Context,
+    file: Path = typer.Argument(..., exists=True, readable=True, resolve_path=True),
+    user_id: Optional[str] = typer.Option(
+        None,
+        "--user-id",
+        help="Optional compatibility field for upload.",
+    ),
+) -> None:
+    try:
+        state: CLIContext = ctx.obj
+        client = MaybeAIClient(state)
+        endpoint = "/api/v1/excel/upload"
+        response = client.upload_file(endpoint, file, user_id=user_id)
+        spreadsheet_url = str(response.get("uri") or response.get("spreadsheet_url") or "")
+        response_doc_id = str(
+            response.get("document_id") or response.get("spreadsheet_id") or ""
+        ) or None
+        _, response_gid = parse_document_target(spreadsheet_url)
+        target = ResolvedTarget(
+            document_id=response_doc_id,
+            url=spreadsheet_url or None,
+            uri=spreadsheet_url or "",
+            gid=response_gid,
+            worksheet_name=None,
+        )
+        render_output(
+            build_command_output(endpoint=endpoint, target=target, result=response),
+            state.output,
+        )
+    except Exception as error:  # pragma: no cover - CLI boundary
+        handle_cli_error(error)

maybeai_sheet/config.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+OutputFormat = Literal["json", "table", "yaml"]
+
+
+@dataclass(slots=True)
+class CLIContext:
+    token: str | None = None
+    base_url: str = "https://play-be.omnimcp.ai"
+    doc_id: str | None = None
+    url: str | None = None
+    uri: str | None = None
+    gid: int | None = None
+    worksheet_name: str | None = None
+    output: OutputFormat = "json"
+    timeout: float = 30.0
+    verbose: bool = False

maybeai_sheet/errors.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+
+class MaybeAISheetError(Exception):
+    """Base exception for CLI failures."""
+
+
+class UsageError(MaybeAISheetError):
+    """User input is incomplete or invalid."""
+
+
+class APIRequestError(MaybeAISheetError):
+    """HTTP request failed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        endpoint: str | None = None,
+        body: object | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.endpoint = endpoint
+        self.body = body

maybeai_sheet/formatters.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+from .config import OutputFormat
+from .errors import APIRequestError, MaybeAISheetError, UsageError
+from .resolver import ResolvedTarget
+
+console = Console()
+
+
+def load_json_file(path: Path) -> Any:
+    return json.loads(path.read_text())
+
+
+def build_command_output(
+    *,
+    endpoint: str,
+    result: Any,
+    target: ResolvedTarget | None = None,
+    verify: Any = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "success": bool(
+            result.get("success", True)
+            if isinstance(result, dict)
+            else True
+        ),
+        "endpoint": endpoint,
+        "result": result,
+    }
+    if target is not None:
+        payload["target"] = target.as_dict()
+    if verify is not None:
+        payload["verify"] = verify
+    return payload
+
+
+def render_output(data: Any, output: OutputFormat) -> None:
+    if output == "json":
+        typer.echo(json.dumps(data, ensure_ascii=False, indent=2))
+        return
+    if output == "yaml":
+        typer.echo(yaml.safe_dump(data, allow_unicode=True, sort_keys=False))
+        return
+    _render_table(data)
+
+
+def _render_table(data: Any) -> None:
+    if isinstance(data, list) and data and all(isinstance(item, dict) for item in data):
+        keys = list({key for item in data for key in item.keys()})
+        table = Table(show_header=True, header_style="bold")
+        for key in keys:
+            table.add_column(str(key))
+        for item in data:
+            table.add_row(*[stringify(item.get(key)) for key in keys])
+        console.print(table)
+        return
+    if isinstance(data, dict):
+        for list_key in ("worksheets", "results", "data", "rows"):
+            value = data.get(list_key)
+            if isinstance(value, list) and value and all(isinstance(item, dict) for item in value):
+                _render_table(value)
+                return
+        table = Table(show_header=False)
+        table.add_column("key", style="bold")
+        table.add_column("value")
+        for key, value in data.items():
+            table.add_row(str(key), stringify(value))
+        console.print(table)
+        return
+    typer.echo(stringify(data))
+
+
+def stringify(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)
+
+
+def handle_cli_error(error: Exception) -> None:
+    if isinstance(error, APIRequestError):
+        payload = {
+            "error": str(error),
+            "status_code": error.status_code,
+            "endpoint": error.endpoint,
+            "body": error.body,
+        }
+        typer.echo(json.dumps(payload, ensure_ascii=False, indent=2), err=True)
+        raise typer.Exit(1)
+    if isinstance(error, (UsageError, MaybeAISheetError)):
+        typer.echo(str(error), err=True)
+        raise typer.Exit(2)
+    raise error

maybeai_sheet/models/__init__.py

@@ -0,0 +1 @@
+"""Pydantic models for MaybeAI Sheet CLI payload validation."""

maybeai_sheet/models/sheet.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ReadSheetRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    worksheet_name: str | None = None
+    range_address: str | None = None
+    value_render_option: str | None = None
+
+
+class ReadHeadersRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+
+
+class ListWorksheetsRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+
+
+class UpdateRangeRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    range_address: str
+    values: list[list[Any]]
+    worksheet_name: str | None = None
+
+
+class AppendRowsRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    data: list[dict[str, Any]]
+    worksheet_name: str | None = None
+
+
+class UpsertRowsRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    data: list[dict[str, Any]]
+    on: list[str]
+    override: bool = False
+    skip_recalculation: bool = False
+
+
+class CreateWorksheetRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str
+    worksheet_name: str
+    values: list[list[Any]] | None = None

maybeai_sheet/models/workbook.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CreateWorkbookRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    sheet_name: str
+    filename: str
+    data: list[dict[str, Any]]
+    column_order: list[str] | None = None

maybeai_sheet/resolver.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
+
+from .config import CLIContext
+from .errors import UsageError
+
+
+@dataclass(slots=True)
+class ResolvedTarget:
+    document_id: str | None
+    url: str | None
+    uri: str
+    gid: int | None
+    worksheet_name: str | None
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def build_document_url(document_id: str) -> str:
+    return f"https://www.maybe.ai/docs/spreadsheets/d/{document_id}"
+
+
+def parse_document_target(url_or_uri: str) -> tuple[str | None, int | None]:
+    parsed = urlparse(url_or_uri)
+    query = parse_qs(parsed.query)
+    gid = None
+    raw_gid = query.get("gid", [None])[0]
+    if raw_gid not in (None, ""):
+        try:
+            gid = int(raw_gid)
+        except (TypeError, ValueError):
+            gid = None
+    document_id = None
+    marker = "/spreadsheets/d/"
+    if marker in parsed.path:
+        document_id = parsed.path.split(marker, 1)[1].split("/", 1)[0]
+    return document_id, gid
+
+
+def append_gid(uri: str, gid: int | None) -> str:
+    if gid is None:
+        return uri
+    parsed = urlparse(uri)
+    query = parse_qs(parsed.query)
+    query["gid"] = [str(gid)]
+    return urlunparse(parsed._replace(query=urlencode(query, doseq=True)))
+
+
+def resolve_target(
+    state: CLIContext,
+    *,
+    require_workbook: bool = True,
+    force_gid_uri: bool = False,
+) -> ResolvedTarget:
+    document_id = state.doc_id
+    url = state.url
+    uri = state.uri
+    gid = state.gid
+
+    if url:
+        parsed_doc_id, parsed_gid = parse_document_target(url)
+        document_id = document_id or parsed_doc_id
+        if gid is None:
+            gid = parsed_gid
+        if uri is None:
+            uri = url
+
+    if uri:
+        parsed_doc_id, parsed_gid = parse_document_target(uri)
+        document_id = document_id or parsed_doc_id
+        if gid is None:
+            gid = parsed_gid
+
+    if uri is None and document_id:
+        url = url or build_document_url(document_id)
+        uri = url
+
+    if require_workbook and not uri:
+        raise UsageError("Provide one of --url, --uri, or --doc-id.")
+
+    if uri is None:
+        uri = ""
+
+    if force_gid_uri:
+        uri = append_gid(uri, gid)
+
+    return ResolvedTarget(
+        document_id=document_id,
+        url=url or (build_document_url(document_id) if document_id else None),
+        uri=uri,
+        gid=gid,
+        worksheet_name=state.worksheet_name,
+    )

maybeai_sheet_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: maybeai-sheet-cli
+Version: 0.1.0
+Summary: CLI for common MaybeAI spreadsheet operations
+Project-URL: Homepage, https://github.com/OmniMCP-AI/maybeai-sheet-cli
+Project-URL: Repository, https://github.com/OmniMCP-AI/maybeai-sheet-cli
+Project-URL: Issues, https://github.com/OmniMCP-AI/maybeai-sheet-cli/issues
+Author: OmniMCP-AI
+License: Proprietary
+Keywords: cli,excel,maybeai,spreadsheet
+Classifier: Environment :: Console
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: rich<14,>=13.7
+Requires-Dist: typer<1,>=0.12
+Description-Content-Type: text/markdown
+
+# maybeai-sheet-cli
+
+CLI for MaybeAI spreadsheet operations.
+
+`maybeai-sheet` wraps the MaybeAI spreadsheet HTTP APIs behind a stable command-line interface so humans, CI jobs, and agents can perform common workbook operations without dynamically generating curl or Python glue.
+
+## Install
+
+```bash
+pip install maybeai-sheet-cli
+```
+
+## Requirements
+
+- Python 3.10+
+- `MAYBEAI_API_TOKEN`
+
+## Quick Start
+
+Set your token:
+
+```bash
+export MAYBEAI_API_TOKEN="YOUR_TOKEN"
+```
+
+List worksheets in a workbook:
+
+```bash
+maybeai-sheet sheet worksheets --doc-id 6a3b3ec9b225d9fe7982ff36
+```
+
+Read a worksheet:
+
+```bash
+maybeai-sheet sheet read --doc-id 6a3b3ec9b225d9fe7982ff36 --worksheet-name "利润分析"
+```
+
+Read headers from a specific worksheet gid:
+
+```bash
+maybeai-sheet sheet headers --doc-id 6a3b3ec9b225d9fe7982ff36 --gid 3
+```
+
+Create a workbook:
+
+```bash
+maybeai-sheet workbook create --title "Board Pack"
+```
+
+Append rows and read back:
+
+```bash
+maybeai-sheet sheet append \
+  --doc-id 6a3b3ec9b225d9fe7982ff36 \
+  --gid 3 \
+  --rows rows.json \
+  --verify
+```
+
+## Command Groups
+
+- `workbook`
+  - `create`
+  - `create-from-file`
+- `sheet`
+  - `read`
+  - `read-range`
+  - `headers`
+  - `worksheets`
+  - `formulas`
+  - `write-range`
+  - `append`
+  - `upsert`
+  - `create-worksheet`
+- `raw`
+  - `post`
+
+## Output
+
+The CLI defaults to JSON output and returns a stable envelope containing:
+
+- `success`
+- `endpoint`
+- `target`
+- `result`
+- optional `verify`
+
+Alternative output modes:
+
+```bash
+maybeai-sheet sheet worksheets --doc-id <DOC_ID> --output table
+maybeai-sheet sheet worksheets --doc-id <DOC_ID> --output yaml
+```
+
+## Development
+
+Create a virtual environment and install editable dependencies:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -U pip
+pip install -e .
+```
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Build distributions:
+
+```bash
+pip install build twine
+python -m build
+twine check dist/*
+```
+
+## Repository Split
+
+This repository owns the software artifact:
+
+- `src/`
+- `tests/`
+- `pyproject.toml`
+- packaging and release concerns
+
+Skill assets were intentionally split out into the sibling repository directory:
+
+- `../maybeai-sheet-cli-skill`
+
+That skill repo owns:
+
+- `SKILL.md`
+- `agents/`
+- `references/`
+- `scripts/`
+- agent-facing workflow documentation

maybeai_sheet_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+maybeai_sheet/__init__.py,sha256=mITbNPcozbaTRi78SCeYTJzXp8mOieNGUARfRfHoMPA,83
+maybeai_sheet/cli.py,sha256=Z8KZLv04gju5Dc2fvI9VlcawdWG3iy-g7yFgIBE4wQs,2901
+maybeai_sheet/client.py,sha256=Ul3WA1Pd6Ka42S6pOZnzBP1Omr0Xz02c4ms-NmU9gMI,2893
+maybeai_sheet/config.py,sha256=7G9PidCSOSgQHuPFvDi2B28JL44-ki1vo8N_tBiLaqo,503
+maybeai_sheet/errors.py,sha256=AnNDsXpSZxw6YKuZwFea8xSoQHAHa3wpINxlo6mZ0gI,602
+maybeai_sheet/formatters.py,sha256=0KoVqAceaIGocHPkiv7DYdmSGTj2FQjWNXee31JdmJg,3045
+maybeai_sheet/resolver.py,sha256=KlnYamHKUmbpvQUxCgolnhKkmJkaaaBWDz_klEBCjMo,2523
+maybeai_sheet/commands/__init__.py,sha256=IpQsdrGmiWn-kZM3PLIIARedIt33UGizUYoh_eSvW6k,44
+maybeai_sheet/commands/raw.py,sha256=FpO9Nl15UPUeFdvYY-fElmRo2EAYYiL1xlBR2VNomLw,1076
+maybeai_sheet/commands/sheet.py,sha256=OVZlEBAnbNrBbPH0f9z6F6oWuTElCxfwtC-HibceV7Y,15632
+maybeai_sheet/commands/workbook.py,sha256=2bGeMzlbQNTH3joB5vqMJZ1QbwmBFQFeI7ztEhyx_T4,3816
+maybeai_sheet/models/__init__.py,sha256=_BlDSPULY-OOZSzoaZ_xZcBiGwI756dfFzz_Vyik-ms,64
+maybeai_sheet/models/sheet.py,sha256=XPmtARMo7xTiFiXeYy8eackL7hWhUXFKR1ltLlibwV0,1254
+maybeai_sheet/models/workbook.py,sha256=sU1_YIQtv6TwwDintuyBD5zBpPkkaZkg51FzrlE_nQ8,303
+maybeai_sheet_cli-0.1.0.dist-info/METADATA,sha256=m1C8ktRNhBX82GnfsK_j-XkZhOptTDDL9f65W2uQXmM,3266
+maybeai_sheet_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+maybeai_sheet_cli-0.1.0.dist-info/entry_points.txt,sha256=9FJHuqT3qUty3ysFlRxu4ntJM7_n7fFEP0GGAE_9rDs,56
+maybeai_sheet_cli-0.1.0.dist-info/RECORD,,

maybeai_sheet_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

maybeai_sheet_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+maybeai-sheet = maybeai_sheet.cli:app