Metadata-Version: 2.4
Name: maybeai-sheet-cli
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
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.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
```
