maybeai-sheet-cli 0.1.0__tar.gz → 0.2.0__tar.gz

maybeai_sheet_cli-0.2.0/CLAUDE.md

@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+## Repo Purpose
+
+This repository contains the `maybeai-sheet` Python CLI for MaybeAI spreadsheet APIs.
+
+## Working Rules
+
+- Keep docs and CLI behavior aligned with the actual code.
+- Prefer small, targeted changes.
+- Do not rename commands or flags unless the implementation changes too.
+- Preserve JSON as the default output format.
+
+## Project Map
+
+- `src/maybeai_sheet/cli.py` - top-level Typer app and global options
+- `src/maybeai_sheet/update.py` - PyPI self-update helpers
+- `src/maybeai_sheet/commands/` - `workbook`, `sheet`, and `raw` command groups
+- `src/maybeai_sheet/client.py` - HTTP client and request helpers
+- `src/maybeai_sheet/resolver.py` - document and worksheet target resolution
+- `src/maybeai_sheet/formatters.py` - JSON, YAML, and table rendering
+- `tests/` - CLI, resolver, and formatter tests
+
+## Common Commands
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+```bash
+python -m maybeai_sheet.cli --help
+```
+
+## Implementation Notes
+
+- Token source order is `--token` then `MAYBEAI_API_TOKEN`.
+- The default API base URL is `https://play-be.omnimcp.ai`.
+- `--doc-id` is converted to a MaybeAI workbook URL when needed.
+- `sheet headers` and formula reads rely on gid-aware URI resolution.
+- `--verify` on write/append/upsert commands reads the sheet back after the write.
+
+## Editing Guidance
+
+- Update README examples when adding or changing commands.
+- Keep request/response examples consistent with the tests.
+- If behavior changes, add or update tests in `tests/` before finishing.

maybeai_sheet_cli-0.2.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: maybeai-sheet-cli
+Version: 0.2.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 for humans, CI jobs, and agents.
+
+## Install
+
+```bash
+pip install maybeai-sheet-cli
+```
+
+Upgrade to the latest release:
+
+```bash
+maybeai-sheet update
+```
+
+Install a specific version:
+
+```bash
+maybeai-sheet update --version 0.2.0
+```
+
+## Requirements
+
+- Python 3.10+
+- `MAYBEAI_API_TOKEN`
+
+## Configure
+
+Set your API token:
+
+```bash
+export MAYBEAI_API_TOKEN="YOUR_TOKEN"
+```
+
+Optional global flags:
+
+- `--base-url` to point at a different MaybeAI API host
+- `--output json|table|yaml`
+- `--timeout <seconds>`
+- `--verbose`
+
+## Quick Start
+
+Read a workbook:
+
+```bash
+maybeai-sheet sheet read --doc-id abc123
+```
+
+List worksheets:
+
+```bash
+maybeai-sheet sheet worksheets --doc-id abc123
+```
+
+Read headers from a worksheet:
+
+```bash
+maybeai-sheet sheet headers --doc-id abc123 --gid 3
+```
+
+Create a workbook:
+
+```bash
+maybeai-sheet workbook create --title "Board Pack"
+```
+
+Append rows and verify:
+
+```bash
+maybeai-sheet sheet append --doc-id abc123 --gid 3 --rows rows.json --verify
+```
+
+## Commands
+
+- `update`
+- `workbook create`
+- `workbook create-from-file`
+- `workbook manifest`
+- `workbook capabilities`
+- `sheet read`
+- `sheet read-range`
+- `sheet read-many`
+- `sheet named-range`
+- `sheet headers`
+- `sheet worksheets`
+- `sheet formulas`
+- `sheet write-range`
+- `sheet clear-range`
+- `sheet append`
+- `sheet formula-set`
+- `sheet formula-batch-set`
+- `sheet recalculate`
+- `sheet upsert`
+- `sheet create-worksheet`
+- `raw post`
+
+## Input Rules
+
+- Use `--doc-id`, `--url`, or `--uri` to identify a workbook.
+- Use `--worksheet-name` when the endpoint supports it.
+- Use `--gid` for gid-specific sheet targeting.
+- File inputs like `--rows`, `--values`, `--targets`, and `--operations` must be JSON.
+
+## Output
+
+Default output is JSON. `table` is optimized for sheet-like payloads; `yaml` is also supported.
+
+## Development
+
+```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
+```

maybeai_sheet_cli-0.2.0/README.md

@@ -0,0 +1,125 @@
+# maybeai-sheet-cli
+
+CLI for MaybeAI spreadsheet operations.
+
+`maybeai-sheet` wraps the MaybeAI spreadsheet HTTP APIs behind a stable command-line interface for humans, CI jobs, and agents.
+
+## Install
+
+```bash
+pip install maybeai-sheet-cli
+```
+
+Upgrade to the latest release:
+
+```bash
+maybeai-sheet update
+```
+
+Install a specific version:
+
+```bash
+maybeai-sheet update --version 0.2.0
+```
+
+## Requirements
+
+- Python 3.10+
+- `MAYBEAI_API_TOKEN`
+
+## Configure
+
+Set your API token:
+
+```bash
+export MAYBEAI_API_TOKEN="YOUR_TOKEN"
+```
+
+Optional global flags:
+
+- `--base-url` to point at a different MaybeAI API host
+- `--output json|table|yaml`
+- `--timeout <seconds>`
+- `--verbose`
+
+## Quick Start
+
+Read a workbook:
+
+```bash
+maybeai-sheet sheet read --doc-id abc123
+```
+
+List worksheets:
+
+```bash
+maybeai-sheet sheet worksheets --doc-id abc123
+```
+
+Read headers from a worksheet:
+
+```bash
+maybeai-sheet sheet headers --doc-id abc123 --gid 3
+```
+
+Create a workbook:
+
+```bash
+maybeai-sheet workbook create --title "Board Pack"
+```
+
+Append rows and verify:
+
+```bash
+maybeai-sheet sheet append --doc-id abc123 --gid 3 --rows rows.json --verify
+```
+
+## Commands
+
+- `update`
+- `workbook create`
+- `workbook create-from-file`
+- `workbook manifest`
+- `workbook capabilities`
+- `sheet read`
+- `sheet read-range`
+- `sheet read-many`
+- `sheet named-range`
+- `sheet headers`
+- `sheet worksheets`
+- `sheet formulas`
+- `sheet write-range`
+- `sheet clear-range`
+- `sheet append`
+- `sheet formula-set`
+- `sheet formula-batch-set`
+- `sheet recalculate`
+- `sheet upsert`
+- `sheet create-worksheet`
+- `raw post`
+
+## Input Rules
+
+- Use `--doc-id`, `--url`, or `--uri` to identify a workbook.
+- Use `--worksheet-name` when the endpoint supports it.
+- Use `--gid` for gid-specific sheet targeting.
+- File inputs like `--rows`, `--values`, `--targets`, and `--operations` must be JSON.
+
+## Output
+
+Default output is JSON. `table` is optimized for sheet-like payloads; `yaml` is also supported.
+
+## Development
+
+```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
+```

{maybeai_sheet_cli-0.1.0 → maybeai_sheet_cli-0.2.0}/cli-packaging-plan.md

@@ -4,13 +4,18 @@
 
 Yes, a CLI is worth adding for the highest-frequency operations, especially:
 
+- `workbook_manifest`
 - `read_sheet`
 - `read_headers`
 - `list_worksheets`
 - `append_rows`
-- `update_data_keep_headers`
 - `update_range_by_lookup`
+- `update_range`
+- `clear_range`
 - `write_new_worksheet`
+- `formula_set`
+- `formula_batch_set`
+- `recalculate_formulas`
 - `workbook_profile`
 - `export`
 
@@ -93,6 +98,8 @@ Resolution rules:
 ```bash
 maybeai-sheet sheet read --doc-id <id> --worksheet-name Sheet1
 maybeai-sheet sheet read --doc-id <id> --worksheet-name Sheet1 --range A1:C20
+maybeai-sheet sheet read-many --doc-id <id> --targets targets.json
+maybeai-sheet sheet named-range --doc-id <id> --name RevenueBlock
 maybeai-sheet sheet headers --doc-id <id> --gid 0
 maybeai-sheet sheet worksheets --doc-id <id>
 maybeai-sheet sheet profile --doc-id <id> --force-refresh
@@ -101,11 +108,14 @@ maybeai-sheet sheet profile --doc-id <id> --force-refresh
 ### Write path
 
 ```bash
-maybeai-sheet sheet append --doc-id <id> --gid 0 --data rows.json
-maybeai-sheet sheet replace --doc-id <id> --worksheet-name Sales --data rows.json
-maybeai-sheet sheet upsert --doc-id <id> --gid 0 --on OrderID --data rows.json
-maybeai-sheet sheet update-range --doc-id <id> --worksheet-name Sheet1 --range A1:C3 --values values.json
-maybeai-sheet sheet new-worksheet --doc-id <id> --worksheet-name Summary --values values.json
+maybeai-sheet sheet append --doc-id <id> --gid 0 --rows rows.json
+maybeai-sheet sheet upsert --doc-id <id> --gid 0 --key OrderID --rows rows.json
+maybeai-sheet sheet write-range --doc-id <id> --worksheet-name Sheet1 --range A1:C3 --values values.json
+maybeai-sheet sheet clear-range --doc-id <id> --worksheet-name Sheet1 --range A1:C3
+maybeai-sheet sheet create-worksheet --doc-id <id> --name Summary --values values.json
+maybeai-sheet sheet formula-set --doc-id <id> --worksheet-name Sheet1 --cell E2 --formula '=SUM(B2:D2)'
+maybeai-sheet sheet formula-batch-set --doc-id <id> --operations ops.json --recalculate-mode worksheet
+maybeai-sheet sheet recalculate --doc-id <id> --worksheet-name Sheet1
 ```
 
 ### File path
@@ -119,7 +129,7 @@ maybeai-sheet file search "q2 forecast"
 ### Escape hatch
 
 ```bash
-maybeai-sheet raw post /api/v1/excel/read_sheet --body body.json
+maybeai-sheet raw post /api/v3/excel/range/read --body body.json
 ```
 
 The `raw` command prevents CLI growth from tracking every niche endpoint.
@@ -128,14 +138,23 @@ The `raw` command prevents CLI growth from tracking every niche endpoint.
 
 | CLI command | API endpoint |
 |---|---|
-| `sheet read` | `POST /api/v1/excel/read_sheet` |
-| `sheet headers` | `POST /api/v1/excel/read_headers` |
-| `sheet worksheets` | `POST /api/v1/excel/list_worksheets` |
-| `sheet append` | `POST /api/v1/excel/append_rows` |
-| `sheet replace` | `POST /api/v1/excel/update_data_keep_headers` |
-| `sheet upsert` | `POST /api/v1/excel/update_range_by_lookup` |
-| `sheet update-range` | `POST /api/v1/excel/update_range` |
-| `sheet new-worksheet` | `POST /api/v1/excel/write_new_worksheet` |
+| `workbook manifest` | `POST /api/v3/excel/workbook/manifest` |
+| `workbook capabilities` | `POST /api/v3/excel/workbook/capabilities` |
+| `sheet read` | `POST /api/v3/excel/range/read` |
+| `sheet read-range` | `POST /api/v3/excel/range/read` |
+| `sheet read-many` | `POST /api/v3/excel/range/read_many` |
+| `sheet named-range` | `POST /api/v3/excel/named_range/read` |
+| `sheet headers` | `POST /api/v3/excel/table/headers` |
+| `sheet worksheets` | `POST /api/v3/excel/worksheet/list` |
+| `sheet formulas` | `POST /api/v3/excel/formula/read` |
+| `sheet append` | `POST /api/v3/excel/table/append_rows` |
+| `sheet upsert` | `POST /api/v3/excel/table/upsert_rows` |
+| `sheet write-range` | `POST /api/v3/excel/range/write` |
+| `sheet clear-range` | `POST /api/v3/excel/range/clear` |
+| `sheet create-worksheet` | `POST /api/v3/excel/worksheet/create` |
+| `sheet formula-set` | `POST /api/v3/excel/formula/set` |
+| `sheet formula-batch-set` | `POST /api/v3/excel/formula/batch_set` |
+| `sheet recalculate` | `POST /api/v3/excel/formula/recalculate` |
 | `sheet profile` | `POST /api/v1/excel/workbook_profile` |
 | `file upload` | `POST /api/v1/excel/upload` |
 | `file export` | `GET /api/v1/excel/export/{document_id}` |
@@ -145,18 +164,20 @@ The `raw` command prevents CLI growth from tracking every niche endpoint.
 The CLI should encode the operational rules already documented in this repo:
 
 1. Warn when neither `--worksheet-name` nor `--gid` is provided for worksheet-sensitive commands
-2. Prefer `--worksheet-name` for `read_sheet`, `update_range`, and `update_data_keep_headers`
-3. Prefer `--gid` for `read_headers`, `append_rows`, and `update_range_by_lookup`
-4. Support `--verify` on write commands to automatically read back after write
-5. Support `--dry-run` where payload generation can be previewed safely
+2. Prefer `workbook manifest` before read/write commands when the target worksheet is not already known
+3. Prefer `--worksheet-name` for `sheet read`, `sheet write-range`, and `sheet formula-set`
+4. Prefer `--gid` for `sheet headers`, `sheet append`, and `sheet upsert`
+5. Support `--verify` on write commands to automatically read back after write
+6. Support `--dry-run` where payload generation can be previewed safely
 
 Example:
 
 ```bash
-maybeai-sheet sheet replace \
+maybeai-sheet sheet upsert \
   --doc-id $DOC_ID \
-  --worksheet-name Sales \
-  --data sales.json \
+  --gid 0 \
+  --key OrderID \
+  --rows sales.json \
   --verify
 ```
 
@@ -209,12 +230,18 @@ Recommended:
 
 Build a thin MVP around the most-used read/write flows:
 
+- `workbook manifest`
 - `sheet read`
 - `sheet headers`
 - `sheet worksheets`
 - `sheet append`
-- `sheet replace`
 - `sheet upsert`
+- `sheet write-range`
+- `sheet clear-range`
+- `sheet create-worksheet`
+- `sheet formula-set`
+- `sheet formula-batch-set`
+- `sheet recalculate`
 - `file upload`
 - `file export`
 

{maybeai_sheet_cli-0.1.0 → maybeai_sheet_cli-0.2.0}/cli-plan.md

@@ -106,6 +106,9 @@ maybeai-sheet sheet read --url "$URL"
 maybeai-sheet sheet read-range --doc-id "$DOC_ID" --gid 3 --range A1:G20
 maybeai-sheet sheet headers --doc-id "$DOC_ID" --worksheet-name "利润分析"
 maybeai-sheet sheet append --doc-id "$DOC_ID" --gid 2 --rows rows.json
+maybeai-sheet sheet clear-range --doc-id "$DOC_ID" --worksheet-name Summary --range D1:F10
+maybeai-sheet sheet formula-set --doc-id "$DOC_ID" --worksheet-name Model --cell E2 --formula "=SUM(B2:D2)"
+maybeai-sheet sheet recalculate --doc-id "$DOC_ID" --worksheet-name Model
 ```
 
 ## Global Flags
@@ -207,15 +210,20 @@ The CLI should wrap the existing API rather than invent a new backend contract.
 | CLI command | Preferred API endpoint |
 |---|---|
 | `workbook create` | workbook creation endpoint or current upload/create API equivalent |
-| `sheet read` | `POST /api/v1/excel/read_sheet` |
-| `sheet read-range` | `POST /api/v1/excel/read_sheet` with bounded range if supported, otherwise CLI-side slice from `read_sheet` only as a fallback |
-| `sheet headers` | `POST /api/v1/excel/read_headers` |
-| `sheet worksheets` | `POST /api/v1/excel/list_worksheets` |
-| `sheet write-range` | `POST /api/v1/excel/update_range` |
-| `sheet append` | `POST /api/v1/excel/append_rows` |
-| `sheet upsert` | `POST /api/v1/excel/update_range_by_lookup` |
-| `sheet create-worksheet` | `POST /api/v1/excel/write_new_worksheet` or worksheet creation endpoint if more exact |
-| `sheet formulas` | formula read endpoint if available, otherwise existing formula inspection path |
+| `workbook manifest` | `POST /api/v3/excel/workbook/manifest` |
+| `workbook capabilities` | `POST /api/v3/excel/workbook/capabilities` |
+| `sheet read` | `POST /api/v3/excel/range/read` |
+| `sheet read-range` | `POST /api/v3/excel/range/read` |
+| `sheet headers` | `POST /api/v3/excel/table/headers` |
+| `sheet worksheets` | `POST /api/v3/excel/worksheet/list` |
+| `sheet write-range` | `POST /api/v3/excel/range/write` |
+| `sheet clear-range` | `POST /api/v3/excel/range/clear` |
+| `sheet append` | `POST /api/v3/excel/table/append_rows` |
+| `sheet upsert` | `POST /api/v3/excel/table/upsert_rows` |
+| `sheet create-worksheet` | `POST /api/v3/excel/worksheet/create` |
+| `sheet formulas` | `POST /api/v3/excel/formula/read` |
+| `sheet formula-set` | `POST /api/v3/excel/formula/set` |
+| `sheet recalculate` | `POST /api/v3/excel/formula/recalculate` |
 
 Two endpoint checks are required before implementation starts:
 

maybeai_sheet_cli-0.2.0/docs/verification-matrix-fallback.md

@@ -0,0 +1,35 @@
+# Verification matrix: v3 → v1 CLI fallback
+
+Hermes Phase A/B compared MCP vs CLI-first vs curl on tasks t1–t4.
+This document scopes what the **CLI fallback layer** covers so results are not
+misread as “full v3 wrapper complete.”
+
+## Covered commands (404 → v1)
+
+| Task | CLI command | v3 primary | v1 fallback |
+|------|-------------|------------|-------------|
+| t1 list worksheets | `sheet worksheets` | `/api/v3/excel/worksheet/list` | `/api/v1/excel/list_worksheets` |
+| t2 read rows | `sheet read` | `/api/v3/excel/range/read` | `/api/v1/excel/read_sheet` |
+| t3 append + verify | `sheet append --verify` | `/api/v3/excel/table/append_rows` | `/api/v1/excel/append_rows` |
+| t3 readback | (verify step) | `/api/v3/excel/range/read` | `/api/v1/excel/read_sheet` |
+| t4 create worksheet | `sheet create-worksheet` | `/api/v3/excel/worksheet/create` | `/api/v1/excel/write_new_worksheet` |
+
+Implementation: `_post_with_fallback()` in `src/maybeai_sheet/commands/sheet.py`.
+Fallback triggers only on HTTP **404** from the v3 endpoint.
+
+## Tests
+
+```bash
+python tests/test_cli.py
+```
+
+Includes `test_sheet_worksheets_falls_back_to_v1_on_404`, `test_sheet_read_falls_back_to_v1_on_404`,
+`test_sheet_append_falls_back_to_v1_on_404_and_verify_read_fallback`,
+`test_sheet_create_worksheet_falls_back_to_v1_on_404`.
+
+## Not covered by this layer
+
+- **curl skill** — no automatic fallback; agent assembles raw HTTP
+- **MCP tools** — separate path; do not use CLI fallback
+- **Non-404 failures** — payload mismatch, auth, 5xx are not retried on v1
+- **Full v3 wrapper plan** — see `docs/finclaw-excel-api-v3-wrapper-plan.md`

{maybeai_sheet_cli-0.1.0 → maybeai_sheet_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "maybeai-sheet-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "CLI for common MaybeAI spreadsheet operations"
 readme = "README.md"
 requires-python = ">=3.10"

{maybeai_sheet_cli-0.1.0 → maybeai_sheet_cli-0.2.0}/src/maybeai_sheet/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{maybeai_sheet_cli-0.1.0 → maybeai_sheet_cli-0.2.0}/src/maybeai_sheet/cli.py

@@ -10,6 +10,7 @@ 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
+from .update import run_update
 
 app = typer.Typer(
     help="CLI for common MaybeAI spreadsheet operations.",
@@ -108,6 +109,31 @@ def main(
         handle_cli_error(error)
 
 
+@app.command("update")
+def update_cli(
+    version: Optional[str] = typer.Option(
+        None,
+        "--version",
+        help="Install a specific PyPI version instead of the latest release.",
+    ),
+    check: bool = typer.Option(
+        False,
+        "--check",
+        help="Compare the installed version with PyPI and exit without installing.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the pip command that would run.",
+    ),
+) -> None:
+    """Update maybeai-sheet-cli from PyPI."""
+    try:
+        run_update(target_version=version, check_only=check, dry_run=dry_run)
+    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")

{maybeai_sheet_cli-0.1.0 → maybeai_sheet_cli-0.2.0}/src/maybeai_sheet/commands/raw.py

@@ -8,6 +8,7 @@ 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 ..options import output_option, resolve_command_state, timeout_option, verbose_option
 
 app = typer.Typer(help="Low-level API escape hatch.", no_args_is_help=True)
 
@@ -24,9 +25,17 @@ def post(
         resolve_path=True,
         help="Optional JSON request body.",
     ),
+    output: Optional[str] = output_option(),
+    verbose: Optional[bool] = verbose_option(),
+    timeout: Optional[float] = timeout_option(),
 ) -> None:
     try:
-        state: CLIContext = ctx.obj
+        state: CLIContext = resolve_command_state(
+            ctx,
+            output=output,
+            verbose=verbose,
+            timeout=timeout,
+        )
         client = MaybeAIClient(state)
         payload = load_json_file(body) if body else {}
         response = client.post_json(path, payload)