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

maybeai_sheet_cli-0.4.0/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: maybeai-sheet-cli
+Version: 0.4.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.
+
+`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
+```
+
+Rename a worksheet and inspect a destructive row delete before sending it:
+
+```bash
+mbs worksheet rename --doc-id abc123 --worksheet-name Old --new-name New
+mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --dry-run
+mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --yes
+```
+
+Search, style, inspect history, and export:
+
+```bash
+mbs range search --doc-id abc123 --worksheet-name Sheet1 --query revenue --max-results 20
+mbs style freeze-panes --doc-id abc123 --worksheet-name Sheet1 --cell B2
+mbs formula calculate --doc-id abc123 --worksheet-name Sheet1 --cell E2 --formula "=SUM(B2:D2)"
+mbs history list --doc-id abc123 --limit 10
+mbs file export --doc-id abc123 --out workbook.xlsx
+```
+
+## Commands
+
+The preferred command groups are `workbook`, `worksheet`, `range`, `table`,
+`row`, `column`, `formula`, `style`, `history`, `file`, `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.
+│   ├── rename             Rename a worksheet.
+│   ├── delete             Delete a worksheet; requires --yes unless --dry-run.
+│   ├── copy               Copy a worksheet.
+│   └── move               Move a worksheet to a zero-based index.
+│
+├── range
+│   ├── read               Read a bounded A1 range.
+│   ├── write              Write a JSON matrix into an A1 range.
+│   ├── clear              Clear an A1 range.
+│   └── search             Search a worksheet with bounded results.
+│
+├── table
+│   ├── headers            Read header row metadata.
+│   ├── append-rows        Append JSON row objects.
+│   └── upsert-rows        Upsert JSON row objects by key.
+│
+├── row
+│   ├── insert             Insert rows.
+│   ├── delete             Delete rows; requires --yes unless --dry-run.
+│   └── move               Move rows.
+│
+├── column
+│   ├── insert             Insert columns.
+│   ├── delete             Delete columns; requires --yes unless --dry-run.
+│   ├── move               Move columns.
+│   └── width              Set column width.
+│
+├── 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.
+│   ├── calculate          Calculate one formula cell.
+│   └── lineage            Trace formula lineage for one cell.
+│
+├── style
+│   ├── freeze-panes       Freeze rows/columns using an A1 cell boundary.
+│   ├── auto-filter set    Set worksheet auto-filter range.
+│   ├── auto-filter remove Remove worksheet auto-filter.
+│   ├── columns-width      Set column widths.
+│   └── rows-height        Set row heights.
+│
+├── history
+│   ├── list               List workbook versions with bounded output.
+│   └── read               Read a workbook version.
+│
+├── file
+│   ├── export             Export workbook bytes to --out.
+│   ├── list               List files with bounded output.
+│   └── search             Search files with bounded output.
+│
+├── 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 `row` and `column` for structural row/column changes.
+- Use `formula` when preserving or changing formulas matters.
+- Use `style` for layout operations like freeze panes, filter ranges, widths, and heights.
+- Use `history` for read-only version inspection.
+- Use `file` for export/list/search file operations.
+- 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.4.0/README.md

@@ -0,0 +1,280 @@
+# 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
+```
+
+Rename a worksheet and inspect a destructive row delete before sending it:
+
+```bash
+mbs worksheet rename --doc-id abc123 --worksheet-name Old --new-name New
+mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --dry-run
+mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --yes
+```
+
+Search, style, inspect history, and export:
+
+```bash
+mbs range search --doc-id abc123 --worksheet-name Sheet1 --query revenue --max-results 20
+mbs style freeze-panes --doc-id abc123 --worksheet-name Sheet1 --cell B2
+mbs formula calculate --doc-id abc123 --worksheet-name Sheet1 --cell E2 --formula "=SUM(B2:D2)"
+mbs history list --doc-id abc123 --limit 10
+mbs file export --doc-id abc123 --out workbook.xlsx
+```
+
+## Commands
+
+The preferred command groups are `workbook`, `worksheet`, `range`, `table`,
+`row`, `column`, `formula`, `style`, `history`, `file`, `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.
+│   ├── rename             Rename a worksheet.
+│   ├── delete             Delete a worksheet; requires --yes unless --dry-run.
+│   ├── copy               Copy a worksheet.
+│   └── move               Move a worksheet to a zero-based index.
+│
+├── range
+│   ├── read               Read a bounded A1 range.
+│   ├── write              Write a JSON matrix into an A1 range.
+│   ├── clear              Clear an A1 range.
+│   └── search             Search a worksheet with bounded results.
+│
+├── table
+│   ├── headers            Read header row metadata.
+│   ├── append-rows        Append JSON row objects.
+│   └── upsert-rows        Upsert JSON row objects by key.
+│
+├── row
+│   ├── insert             Insert rows.
+│   ├── delete             Delete rows; requires --yes unless --dry-run.
+│   └── move               Move rows.
+│
+├── column
+│   ├── insert             Insert columns.
+│   ├── delete             Delete columns; requires --yes unless --dry-run.
+│   ├── move               Move columns.
+│   └── width              Set column width.
+│
+├── 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.
+│   ├── calculate          Calculate one formula cell.
+│   └── lineage            Trace formula lineage for one cell.
+│
+├── style
+│   ├── freeze-panes       Freeze rows/columns using an A1 cell boundary.
+│   ├── auto-filter set    Set worksheet auto-filter range.
+│   ├── auto-filter remove Remove worksheet auto-filter.
+│   ├── columns-width      Set column widths.
+│   └── rows-height        Set row heights.
+│
+├── history
+│   ├── list               List workbook versions with bounded output.
+│   └── read               Read a workbook version.
+│
+├── file
+│   ├── export             Export workbook bytes to --out.
+│   ├── list               List files with bounded output.
+│   └── search             Search files with bounded output.
+│
+├── 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 `row` and `column` for structural row/column changes.
+- Use `formula` when preserving or changing formulas matters.
+- Use `style` for layout operations like freeze panes, filter ranges, widths, and heights.
+- Use `history` for read-only version inspection.
+- Use `file` for export/list/search file operations.
+- 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
+```