maybeai-sheet-cli 0.1.0__tar.gz

maybeai_sheet_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__google-search__performGoogleSearch",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:advenboost.com)"
+    ]
+  }
+}

maybeai_sheet_cli-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# python generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# venv
+.venv/
+
+.env
+.envrc
+.pre-commit-config.yaml
+.idea
+*.log
+.DS_Store
+benches/data/
+.cursor
+ig/
+.cursorrules
+temp
+.clauderc.json
+docs_requirement
+artifacts/

maybeai_sheet_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,139 @@
+# 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/cli-packaging-plan.md

@@ -0,0 +1,252 @@
+# MaybeAI Sheet CLI Plan
+
+## Recommendation
+
+Yes, a CLI is worth adding for the highest-frequency operations, especially:
+
+- `read_sheet`
+- `read_headers`
+- `list_worksheets`
+- `append_rows`
+- `update_data_keep_headers`
+- `update_range_by_lookup`
+- `write_new_worksheet`
+- `workbook_profile`
+- `export`
+
+It is **not** a good replacement for the entire API surface. The repo already shows a large endpoint set, so the right design is:
+
+1. First-class commands for the common workflows
+2. Stable shared flags for auth, workbook, and worksheet targeting
+3. A generic `api` or `raw` command for less-used endpoints
+
+That keeps the CLI small enough to publish and maintain.
+
+## Why a CLI Helps
+
+For common sheet work, the current `curl` scripts have three recurring costs:
+
+- repeated auth and base URL boilerplate
+- repeated `uri` and `gid` handling
+- repeated JSON escaping for structured payloads
+
+A CLI improves:
+
+- usability for humans
+- repeatability in scripts and CI
+- discoverability through `--help`
+- safer worksheet targeting through shared options
+
+## Product Scope
+
+Package name candidates:
+
+- `maybeai-sheet`
+- `maybeai-sheets`
+- `maybe-sheet`
+
+Recommended executable:
+
+```bash
+maybeai-sheet
+```
+
+Recommended Python baseline:
+
+- Python `>=3.10`
+
+Recommended implementation:
+
+- `typer` for CLI
+- `httpx` for HTTP client
+- `pydantic` for payload validation
+- `rich` for readable table / JSON output
+
+## CLI Shape
+
+```bash
+maybeai-sheet [global options] <resource> <command> [command options]
+```
+
+Global options:
+
+- `--token` or env `MAYBEAI_API_TOKEN`
+- `--base-url` default `https://play-be.omnimcp.ai`
+- `--doc-id`
+- `--uri`
+- `--gid`
+- `--worksheet-name`
+- `--output json|table|yaml`
+- `--verbose`
+
+Resolution rules:
+
+1. If `--uri` is provided, use it
+2. Else if `--doc-id` is provided, build `https://www.maybe.ai/docs/spreadsheets/d/<doc_id>`
+3. If `--gid` is provided, append `?gid=<gid>` where required
+4. Prefer `--worksheet-name` for commands that support it
+
+## Proposed Commands
+
+### Read path
+
+```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 headers --doc-id <id> --gid 0
+maybeai-sheet sheet worksheets --doc-id <id>
+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
+```
+
+### File path
+
+```bash
+maybeai-sheet file upload ./report.xlsx
+maybeai-sheet file export --doc-id <id> --out final.xlsx
+maybeai-sheet file search "q2 forecast"
+```
+
+### Escape hatch
+
+```bash
+maybeai-sheet raw post /api/v1/excel/read_sheet --body body.json
+```
+
+The `raw` command prevents CLI growth from tracking every niche endpoint.
+
+## Command Mapping
+
+| 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` |
+| `sheet profile` | `POST /api/v1/excel/workbook_profile` |
+| `file upload` | `POST /api/v1/excel/upload` |
+| `file export` | `GET /api/v1/excel/export/{document_id}` |
+
+## UX Rules
+
+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
+
+Example:
+
+```bash
+maybeai-sheet sheet replace \
+  --doc-id $DOC_ID \
+  --worksheet-name Sales \
+  --data sales.json \
+  --verify
+```
+
+## Suggested Package Layout
+
+```text
+src/maybeai_sheet/
+  __init__.py
+  cli.py
+  config.py
+  client.py
+  models.py
+  formatters.py
+  commands/
+    file.py
+    sheet.py
+    raw.py
+tests/
+pyproject.toml
+README.md
+```
+
+## `pyproject.toml` Direction
+
+Use a console script entry point:
+
+```toml
+[project]
+name = "maybeai-sheet"
+version = "0.1.0"
+description = "CLI for common MaybeAI spreadsheet operations"
+requires-python = ">=3.10"
+dependencies = ["typer", "httpx", "pydantic", "rich"]
+
+[project.scripts]
+maybeai-sheet = "maybeai_sheet.cli:app"
+```
+
+Build backend:
+
+- `hatchling` or `setuptools`
+
+Recommended:
+
+- `hatchling`
+
+## Publish-to-PyPI Plan
+
+### Phase 1
+
+Build a thin MVP around the most-used read/write flows:
+
+- `sheet read`
+- `sheet headers`
+- `sheet worksheets`
+- `sheet append`
+- `sheet replace`
+- `sheet upsert`
+- `file upload`
+- `file export`
+
+### Phase 2
+
+Add operator-safety and better UX:
+
+- `--verify`
+- `--output table`
+- better error messages for auth and wrong-sheet targeting
+- `sheet profile`
+
+### Phase 3
+
+Publish:
+
+1. reserve package name on PyPI
+2. add `pyproject.toml`
+3. add README with install and auth setup
+4. add tests for request construction
+5. build with `python -m build`
+6. publish with `twine upload dist/*` or trusted publishing
+
+## What Not To Do
+
+- Do not create one CLI command per endpoint on day one
+- Do not force users to hand-build JSON strings for common commands
+- Do not hide worksheet targeting semantics
+- Do not publish before adding at least smoke tests for the common commands
+
+## Bottom Line
+
+Yes, a pip-published CLI is a good fit here, but only if it is opinionated around the top workflows and does not try to mirror the full backend surface.
+
+The first command to optimize is `read_sheet`, followed by the table-safe write commands.