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
```
