maybeai-sheet-cli 0.3.0__tar.gz → 0.3.2__tar.gz

maybeai_sheet_cli-0.3.2/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: maybeai-sheet-cli
+Version: 0.3.2
+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.
+
+`mbs` wraps the MaybeAI spreadsheet HTTP APIs behind a stable command-line interface for humans, CI jobs, and agents.
+
+## Install
+
+On Debian/Ubuntu and other **PEP 668** systems, do **not** use bare `pip install` on system Python. Use **pipx** (recommended for CLIs):
+
+```bash
+sudo apt install -y pipx python3-venv
+pipx ensurepath
+# re-login or: source ~/.bashrc
+
+pipx install maybeai-sheet-cli
+mbs --version
+```
+
+For local venvs or macOS/dev machines, plain pip is fine:
+
+```bash
+pip install maybeai-sheet-cli
+```
+
+Upgrade to the latest release:
+
+```bash
+mbs update          # when installed via pip or pipx
+pipx upgrade maybeai-sheet-cli   # alternative on pipx installs
+```
+
+Install a specific version:
+
+```bash
+mbs update --version 0.3.2
+pipx install maybeai-sheet-cli==0.3.2 --force   # pipx reinstall pin
+```
+
+Uninstall:
+
+```bash
+pipx uninstall maybeai-sheet-cli
+# not: pip uninstall -U  (-U is invalid for uninstall)
+```
+
+## 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 bounded range:
+
+```bash
+mbs range read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
+```
+
+List worksheets:
+
+```bash
+mbs worksheet list --doc-id abc123
+```
+
+Read headers from a worksheet:
+
+```bash
+mbs table headers --doc-id abc123 --gid 3
+```
+
+Create a workbook:
+
+```bash
+mbs workbook create --title "Board Pack"
+```
+
+Upload a workbook-style `.xlsx` through the default Excelize path:
+
+```bash
+mbs workbook import ./report.xlsx
+```
+
+Import a large table-like `.xlsx` into SheetTable/PG:
+
+```bash
+mbs workbook import ./large-table.xlsx --engine postgres
+```
+
+Append rows and verify:
+
+```bash
+mbs table append-rows --doc-id abc123 --gid 3 --rows rows.json --verify
+```
+
+Make a workbook public for viewers:
+
+```bash
+mbs share visibility --doc-id abc123 --visibility public --public-permission viewer
+```
+
+## Commands
+
+The preferred command groups are `workbook`, `worksheet`, `range`, `table`,
+`formula`, `share`, and `raw`. The older `sheet ...` commands remain available
+as compatibility aliases.
+
+```text
+mbs
+├── update
+│   └── Update maybeai-sheet-cli from PyPI.
+│
+├── workbook
+│   ├── create             Create a new workbook.
+│   ├── create-from-file   Upload/import an .xlsx file.
+│   ├── import             Preferred alias for create-from-file.
+│   ├── manifest           Inspect workbook profile and routing metadata.
+│   └── capabilities       Inspect workbook capability/profile metadata.
+│
+├── worksheet
+│   ├── list               List worksheets in a workbook.
+│   └── create             Create a worksheet, optionally with starter values.
+│
+├── range
+│   ├── read               Read a bounded A1 range.
+│   ├── write              Write a JSON matrix into an A1 range.
+│   └── clear              Clear an A1 range.
+│
+├── table
+│   ├── headers            Read header row metadata.
+│   ├── append-rows        Append JSON row objects.
+│   └── upsert-rows        Upsert JSON row objects by key.
+│
+├── formula
+│   ├── read               Read formulas with FORMULA render mode.
+│   ├── set                Set one formula cell.
+│   ├── batch-set          Set formula ranges from a JSON operations file.
+│   └── recalculate        Recalculate formulas for a worksheet/workbook.
+│
+├── share
+│   ├── visibility         Set workbook visibility.
+│   ├── grant              Grant a user permission.
+│   ├── permission         Read current permission.
+│   ├── remove             Remove a user's access.
+│   └── list               List sharing entries.
+│
+├── raw
+│   └── post               Low-level POST escape hatch for routed API paths.
+│
+└── sheet                  Legacy compatibility aliases.
+    ├── read
+    ├── read-range
+    ├── read-many
+    ├── named-range
+    ├── headers
+    ├── worksheets
+    ├── formulas
+    ├── write-range
+    ├── clear-range
+    ├── append
+    ├── upsert
+    ├── formula-set
+    ├── formula-batch-set
+    ├── recalculate
+    └── create-worksheet
+```
+
+Relationship guide:
+
+- Use `workbook` for file-level creation, upload/import, and manifest checks.
+- Use `worksheet` for tab lifecycle operations.
+- Use `range` for coordinate-based reads and writes.
+- Use `table` when data is row-object shaped and keyed by headers.
+- Use `formula` when preserving or changing formulas matters.
+- Use `share` for visibility and collaborator access.
+- Use `raw post` only when a first-class command does not exist yet.
+
+Targeting notes:
+
+- Most commands accept `--doc-id`, `--url`, or `--uri`.
+- Prefer `--worksheet-name` when the backend route supports names.
+- Use `--gid` for gid-specific table operations; live verification showed
+  `table upsert-rows` is safest with `--gid`.
+
+## 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.3.2/README.md

@@ -0,0 +1,224 @@
+# maybeai-sheet-cli
+
+CLI for MaybeAI spreadsheet operations.
+
+`mbs` wraps the MaybeAI spreadsheet HTTP APIs behind a stable command-line interface for humans, CI jobs, and agents.
+
+## Install
+
+On Debian/Ubuntu and other **PEP 668** systems, do **not** use bare `pip install` on system Python. Use **pipx** (recommended for CLIs):
+
+```bash
+sudo apt install -y pipx python3-venv
+pipx ensurepath
+# re-login or: source ~/.bashrc
+
+pipx install maybeai-sheet-cli
+mbs --version
+```
+
+For local venvs or macOS/dev machines, plain pip is fine:
+
+```bash
+pip install maybeai-sheet-cli
+```
+
+Upgrade to the latest release:
+
+```bash
+mbs update          # when installed via pip or pipx
+pipx upgrade maybeai-sheet-cli   # alternative on pipx installs
+```
+
+Install a specific version:
+
+```bash
+mbs update --version 0.3.2
+pipx install maybeai-sheet-cli==0.3.2 --force   # pipx reinstall pin
+```
+
+Uninstall:
+
+```bash
+pipx uninstall maybeai-sheet-cli
+# not: pip uninstall -U  (-U is invalid for uninstall)
+```
+
+## 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 bounded range:
+
+```bash
+mbs range read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
+```
+
+List worksheets:
+
+```bash
+mbs worksheet list --doc-id abc123
+```
+
+Read headers from a worksheet:
+
+```bash
+mbs table headers --doc-id abc123 --gid 3
+```
+
+Create a workbook:
+
+```bash
+mbs workbook create --title "Board Pack"
+```
+
+Upload a workbook-style `.xlsx` through the default Excelize path:
+
+```bash
+mbs workbook import ./report.xlsx
+```
+
+Import a large table-like `.xlsx` into SheetTable/PG:
+
+```bash
+mbs workbook import ./large-table.xlsx --engine postgres
+```
+
+Append rows and verify:
+
+```bash
+mbs table append-rows --doc-id abc123 --gid 3 --rows rows.json --verify
+```
+
+Make a workbook public for viewers:
+
+```bash
+mbs share visibility --doc-id abc123 --visibility public --public-permission viewer
+```
+
+## Commands
+
+The preferred command groups are `workbook`, `worksheet`, `range`, `table`,
+`formula`, `share`, and `raw`. The older `sheet ...` commands remain available
+as compatibility aliases.
+
+```text
+mbs
+├── update
+│   └── Update maybeai-sheet-cli from PyPI.
+│
+├── workbook
+│   ├── create             Create a new workbook.
+│   ├── create-from-file   Upload/import an .xlsx file.
+│   ├── import             Preferred alias for create-from-file.
+│   ├── manifest           Inspect workbook profile and routing metadata.
+│   └── capabilities       Inspect workbook capability/profile metadata.
+│
+├── worksheet
+│   ├── list               List worksheets in a workbook.
+│   └── create             Create a worksheet, optionally with starter values.
+│
+├── range
+│   ├── read               Read a bounded A1 range.
+│   ├── write              Write a JSON matrix into an A1 range.
+│   └── clear              Clear an A1 range.
+│
+├── table
+│   ├── headers            Read header row metadata.
+│   ├── append-rows        Append JSON row objects.
+│   └── upsert-rows        Upsert JSON row objects by key.
+│
+├── formula
+│   ├── read               Read formulas with FORMULA render mode.
+│   ├── set                Set one formula cell.
+│   ├── batch-set          Set formula ranges from a JSON operations file.
+│   └── recalculate        Recalculate formulas for a worksheet/workbook.
+│
+├── share
+│   ├── visibility         Set workbook visibility.
+│   ├── grant              Grant a user permission.
+│   ├── permission         Read current permission.
+│   ├── remove             Remove a user's access.
+│   └── list               List sharing entries.
+│
+├── raw
+│   └── post               Low-level POST escape hatch for routed API paths.
+│
+└── sheet                  Legacy compatibility aliases.
+    ├── read
+    ├── read-range
+    ├── read-many
+    ├── named-range
+    ├── headers
+    ├── worksheets
+    ├── formulas
+    ├── write-range
+    ├── clear-range
+    ├── append
+    ├── upsert
+    ├── formula-set
+    ├── formula-batch-set
+    ├── recalculate
+    └── create-worksheet
+```
+
+Relationship guide:
+
+- Use `workbook` for file-level creation, upload/import, and manifest checks.
+- Use `worksheet` for tab lifecycle operations.
+- Use `range` for coordinate-based reads and writes.
+- Use `table` when data is row-object shaped and keyed by headers.
+- Use `formula` when preserving or changing formulas matters.
+- Use `share` for visibility and collaborator access.
+- Use `raw post` only when a first-class command does not exist yet.
+
+Targeting notes:
+
+- Most commands accept `--doc-id`, `--url`, or `--uri`.
+- Prefer `--worksheet-name` when the backend route supports names.
+- Use `--gid` for gid-specific table operations; live verification showed
+  `table upsert-rows` is safest with `--gid`.
+
+## 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.3.0 → maybeai_sheet_cli-0.3.2}/cli-packaging-plan.md

@@ -44,16 +44,16 @@ A CLI improves:
 
 ## Product Scope
 
-Package name candidates:
+Package identity:
 
-- `maybeai-sheet`
-- `maybeai-sheets`
-- `maybe-sheet`
+- distribution name: `maybeai-sheet-cli`
+- executable: `mbs`
+- import package: `maybeai_sheet`
 
 Recommended executable:
 
 ```bash
-maybeai-sheet
+mbs
 ```
 
 Recommended Python baseline:
@@ -70,7 +70,7 @@ Recommended implementation:
 ## CLI Shape
 
 ```bash
-maybeai-sheet [global options] <resource> <command> [command options]
+mbs [global options] <resource> <command> [command options]
 ```
 
 Global options:
@@ -96,40 +96,40 @@ Resolution rules:
 ### 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 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
+mbs sheet read --doc-id <id> --worksheet-name Sheet1
+mbs sheet read --doc-id <id> --worksheet-name Sheet1 --range A1:C20
+mbs sheet read-many --doc-id <id> --targets targets.json
+mbs sheet named-range --doc-id <id> --name RevenueBlock
+mbs sheet headers --doc-id <id> --gid 0
+mbs sheet worksheets --doc-id <id>
+mbs sheet profile --doc-id <id> --force-refresh
 ```
 
 ### Write path
 
 ```bash
-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
+mbs sheet append --doc-id <id> --gid 0 --rows rows.json
+mbs sheet upsert --doc-id <id> --gid 0 --key OrderID --rows rows.json
+mbs sheet write-range --doc-id <id> --worksheet-name Sheet1 --range A1:C3 --values values.json
+mbs sheet clear-range --doc-id <id> --worksheet-name Sheet1 --range A1:C3
+mbs sheet create-worksheet --doc-id <id> --name Summary --values values.json
+mbs sheet formula-set --doc-id <id> --worksheet-name Sheet1 --cell E2 --formula '=SUM(B2:D2)'
+mbs sheet formula-batch-set --doc-id <id> --operations ops.json --recalculate-mode worksheet
+mbs sheet recalculate --doc-id <id> --worksheet-name Sheet1
 ```
 
 ### 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"
+mbs file upload ./report.xlsx
+mbs file export --doc-id <id> --out final.xlsx
+mbs file search "q2 forecast"
 ```
 
 ### Escape hatch
 
 ```bash
-maybeai-sheet raw post /api/v3/excel/range/read --body body.json
+mbs raw post /api/v3/excel/range/read --body body.json
 ```
 
 The `raw` command prevents CLI growth from tracking every niche endpoint.
@@ -173,7 +173,7 @@ The CLI should encode the operational rules already documented in this repo:
 Example:
 
 ```bash
-maybeai-sheet sheet upsert \
+mbs sheet upsert \
   --doc-id $DOC_ID \
   --gid 0 \
   --key OrderID \
@@ -206,14 +206,14 @@ Use a console script entry point:
 
 ```toml
 [project]
-name = "maybeai-sheet"
-version = "0.1.0"
+name = "maybeai-sheet-cli"
+version = "0.3.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"
+mbs = "maybeai_sheet.cli:app"
 ```
 
 Build backend:

{maybeai_sheet_cli-0.3.0 → maybeai_sheet_cli-0.3.2}/cli-plan.md

@@ -2,14 +2,14 @@
 
 ## Goal
 
-Add a stable `maybeai-sheet` CLI in front of the existing curl-first skill so agents and humans can invoke the highest-value spreadsheet operations without dynamically generating shell or Python glue.
+Add a stable `mbs` CLI in front of the existing curl-first skill so agents and humans can invoke the highest-value spreadsheet operations without dynamically generating shell or Python glue.
 
 This plan intentionally focuses on the most useful commands first and does not include `rename_worksheet`.
 
 Repository naming:
 
 - project directory: `maybeai-sheet-cli`
-- installed executable: `maybeai-sheet`
+- installed executable: `mbs`
 - import package: `maybeai_sheet`
 
 ## Why This CLI Should Exist
@@ -41,13 +41,13 @@ The target behavior is:
 Recommended executable:
 
 ```bash
-maybeai-sheet
+mbs
 ```
 
 Recommended package identity:
 
-- distribution name: `maybeai-sheet-cli` or `maybeai-sheet`
-- console script: `maybeai-sheet`
+- distribution name: `maybeai-sheet-cli`
+- console script: `mbs`
 - Python module: `maybeai_sheet`
 
 Recommended baseline:
@@ -89,7 +89,7 @@ Not in the top 10 for this phase:
 ## CLI Shape
 
 ```bash
-maybeai-sheet [global options] <resource> <command> [command options]
+mbs [global options] <resource> <command> [command options]
 ```
 
 Proposed high-level groups:
@@ -101,14 +101,14 @@ Proposed high-level groups:
 Example command style:
 
 ```bash
-maybeai-sheet workbook create --title "Q2 Review"
-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
+mbs workbook create --title "Q2 Review"
+mbs sheet read --url "$URL"
+mbs sheet read-range --doc-id "$DOC_ID" --gid 3 --range A1:G20
+mbs sheet headers --doc-id "$DOC_ID" --worksheet-name "利润分析"
+mbs sheet append --doc-id "$DOC_ID" --gid 2 --rows rows.json
+mbs sheet clear-range --doc-id "$DOC_ID" --worksheet-name Summary --range D1:F10
+mbs sheet formula-set --doc-id "$DOC_ID" --worksheet-name Model --cell E2 --formula "=SUM(B2:D2)"
+mbs sheet recalculate --doc-id "$DOC_ID" --worksheet-name Model
 ```
 
 ## Global Flags
@@ -159,8 +159,8 @@ Validation rules:
 ### Workbook Commands
 
 ```bash
-maybeai-sheet workbook create --title "Board Pack"
-maybeai-sheet workbook create --title "Board Pack" --sheet-name Summary
+mbs workbook create --title "Board Pack"
+mbs workbook create --title "Board Pack" --sheet-name Summary
 ```
 
 Primary responsibility:
@@ -172,11 +172,11 @@ Primary responsibility:
 ### Sheet Read Commands
 
 ```bash
-maybeai-sheet sheet read --doc-id "$DOC_ID" --worksheet-name Sheet1
-maybeai-sheet sheet read-range --doc-id "$DOC_ID" --gid 3 --range A1:G20
-maybeai-sheet sheet headers --doc-id "$DOC_ID" --gid 3
-maybeai-sheet sheet worksheets --doc-id "$DOC_ID"
-maybeai-sheet sheet formulas --doc-id "$DOC_ID" --worksheet-name Model
+mbs sheet read --doc-id "$DOC_ID" --worksheet-name Sheet1
+mbs sheet read-range --doc-id "$DOC_ID" --gid 3 --range A1:G20
+mbs sheet headers --doc-id "$DOC_ID" --gid 3
+mbs sheet worksheets --doc-id "$DOC_ID"
+mbs sheet formulas --doc-id "$DOC_ID" --worksheet-name Model
 ```
 
 Responsibilities:
@@ -190,10 +190,10 @@ Responsibilities:
 ### Sheet Write Commands
 
 ```bash
-maybeai-sheet sheet write-range --doc-id "$DOC_ID" --worksheet-name Summary --range A1:C3 --values values.json
-maybeai-sheet sheet append --doc-id "$DOC_ID" --gid 2 --rows rows.json
-maybeai-sheet sheet upsert --doc-id "$DOC_ID" --gid 2 --key order_id --rows rows.json
-maybeai-sheet sheet create-worksheet --doc-id "$DOC_ID" --worksheet-name Summary --values values.json
+mbs sheet write-range --doc-id "$DOC_ID" --worksheet-name Summary --range A1:C3 --values values.json
+mbs sheet append --doc-id "$DOC_ID" --gid 2 --rows rows.json
+mbs sheet upsert --doc-id "$DOC_ID" --gid 2 --key order_id --rows rows.json
+mbs sheet create-worksheet --doc-id "$DOC_ID" --worksheet-name Summary --values values.json
 ```
 
 Responsibilities:
@@ -244,7 +244,7 @@ The CLI should encode the operational rules already documented in the skill.
 Example:
 
 ```bash
-maybeai-sheet sheet append \
+mbs sheet append \
   --doc-id "$DOC_ID" \
   --gid 3 \
   --rows rows.json \