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

{maybeai_sheet_cli-0.2.0 → maybeai_sheet_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maybeai-sheet-cli
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -26,10 +26,23 @@ Description-Content-Type: text/markdown
 
 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.
+`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
 ```
@@ -37,13 +50,22 @@ pip install maybeai-sheet-cli
 Upgrade to the latest release:
 
 ```bash
-maybeai-sheet update
+mbs update          # when installed via pip or pipx
+pipx upgrade maybeai-sheet-cli   # alternative on pipx installs
 ```
 
 Install a specific version:
 
 ```bash
-maybeai-sheet update --version 0.2.0
+mbs update --version 0.3.1
+pipx install maybeai-sheet-cli==0.3.1 --force   # pipx reinstall pin
+```
+
+Uninstall:
+
+```bash
+pipx uninstall maybeai-sheet-cli
+# not: pip uninstall -U  (-U is invalid for uninstall)
 ```
 
 ## Requirements
@@ -68,43 +90,83 @@ Optional global flags:
 
 ## Quick Start
 
-Read a workbook:
+Read a bounded range:
 
 ```bash
-maybeai-sheet sheet read --doc-id abc123
+mbs range read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
 ```
 
 List worksheets:
 
 ```bash
-maybeai-sheet sheet worksheets --doc-id abc123
+mbs worksheet list --doc-id abc123
 ```
 
 Read headers from a worksheet:
 
 ```bash
-maybeai-sheet sheet headers --doc-id abc123 --gid 3
+mbs table headers --doc-id abc123 --gid 3
 ```
 
 Create a workbook:
 
 ```bash
-maybeai-sheet workbook create --title "Board Pack"
+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
-maybeai-sheet sheet append --doc-id abc123 --gid 3 --rows rows.json --verify
+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.
+
 - `update`
 - `workbook create`
 - `workbook create-from-file`
+- `workbook import`
 - `workbook manifest`
 - `workbook capabilities`
+- `worksheet list`
+- `worksheet create`
+- `range read`
+- `range write`
+- `range clear`
+- `table headers`
+- `table append-rows`
+- `table upsert-rows`
+- `formula read`
+- `formula set`
+- `formula batch-set`
+- `formula recalculate`
+- `share visibility`
+- `share grant`
+- `share permission`
+- `share remove`
+- `share list`
 - `sheet read`
 - `sheet read-range`
 - `sheet read-many`

maybeai_sheet_cli-0.3.1/README.md

@@ -0,0 +1,187 @@
+# 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.1
+pipx install maybeai-sheet-cli==0.3.1 --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.
+
+- `update`
+- `workbook create`
+- `workbook create-from-file`
+- `workbook import`
+- `workbook manifest`
+- `workbook capabilities`
+- `worksheet list`
+- `worksheet create`
+- `range read`
+- `range write`
+- `range clear`
+- `table headers`
+- `table append-rows`
+- `table upsert-rows`
+- `formula read`
+- `formula set`
+- `formula batch-set`
+- `formula recalculate`
+- `share visibility`
+- `share grant`
+- `share permission`
+- `share remove`
+- `share list`
+- `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 → maybeai_sheet_cli-0.3.1}/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.2.0 → maybeai_sheet_cli-0.3.1}/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 \