Moltsheet - Spreadsheets for AI agents

Use the Moltsheet CLI to manage spreadsheet-style data for AI workflows: create sheets, inspect schemas, import rows, update cells, share sheets, and run rea...

installs

stars

karma

SkillRank score ↗

8.2/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-06-08

moltsheet provides a cli-first interface for agents to create, query, and mutate spreadsheet data with sql support, bulk import handling, and explicit error codes for recovery.

structure

9.0

trigger phrases

8.0

procedure

9.0

edge cases

7.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

---
name: moltsheet
description: >-
  Use the Moltsheet CLI to manage spreadsheet-style data for AI workflows: create sheets, inspect schemas, import rows, update cells, share sheets, and run read-only SQL queries over accessible sheets. Use when Codex needs Moltsheet data access, filtered reads, selected columns, joins, aggregates, or spreadsheet mutations. Prefer the CLI over raw HTTP, authenticate once, use `--json`, and use files or stdin for structured payloads.
version: 1.0.8
---

# Moltsheet

Moltsheet is a spreadsheet API for AI agents with a CLI designed to be easier and safer for agents than handwritten HTTP requests.

If you need to create sheets, inspect data, query filtered data, import rows, update cells, or share sheets with another agent, use the CLI first.

## Default Agent Procedure

When handling Moltsheet as an agent, follow this order:

1. Confirm the CLI is available: `moltsheet --version`
2. If it is not installed, use `npx moltsheet@latest ...` or install it globally
3. Authenticate once with `moltsheet auth login`
4. Confirm your agent identity with `moltsheet whoami --json`
5. Prefer `--json` whenever another tool, script, or agent will read the output
6. Use `sql tables` before SQL queries, so you know the accessible table and column names
7. Use `sheet list` and `sheet get` before writing, so you understand the target schema
8. Use stdin or JSON files for structured inputs instead of hand-escaped inline JSON
9. Use raw HTTP only if the CLI cannot be run

## Install

Preferred global install:

```bash
npm install -g moltsheet
```

One-off usage without installing:

```bash
npx moltsheet@latest auth status
```

If you are working inside the Moltsheet repository itself, you can also run the local build:

```bash
npm --prefix cli install
npm run build:cli
npm run cli -- auth status
```

## Authentication

Authenticate once:

```bash
moltsheet auth login
```

Or pass the API key directly:

```bash
moltsheet auth login --api-key YOUR_API_KEY
```

Check current auth state:

```bash
moltsheet auth status --json
```

Show the current agent identity without exposing the API key:

```bash
moltsheet whoami --json
```

Clear stored auth:

```bash
moltsheet auth logout
```

Credential resolution order:

1. `--api-key`
2. `MOLTSHEET_API_KEY`
3. Stored local credential from `auth login`

Storage behavior:

- Preferred: OS credential storage through `keytar`
- Windows: Credential Manager
- macOS: Keychain
- Linux: Secret Service or libsecret
- Fallback: local config file if secure storage is unavailable

The CLI targets the production Moltsheet service by default:

```bash
https://www.moltsheet.com
```

## Commands Agents Should Reach For First

Register an agent:

```bash
moltsheet agent register --display-name "Research Bot" --slug research.bot --json
```

Identify the authenticated agent:

```bash
moltsheet whoami --json
```

List sheets:

```bash
moltsheet sheet list --json
```

Inspect one sheet:

```bash
moltsheet sheet get SHEET_ID --json
```

Read a filtered subset of a sheet:

```bash
moltsheet sheet get SHEET_ID --columns "Company,Qualified" --filter "Qualified:eq:true" --json
```

List SQL table names for accessible sheets:

```bash
moltsheet sql tables --json
```

Run a read-only SQL query against those sheet-like tables:

```bash
moltsheet sql query --query "select company, website from leads where qualified = true limit 10" --json
```

Read SQL from a file:

```bash
moltsheet sql query --file query.sql --json
```

Read SQL from stdin with a lower result cap:

```bash
cat query.sql | moltsheet sql query --stdin --limit 500 --json
```

## SQL Query Workflow

Use SQL when you need filtered rows, selected columns, joins, grouping, counts, sorting, or other read-only analysis without downloading full sheet rows.

1. Run `moltsheet sql tables --json`.
2. Pick a table name from `sqlName` or `sqlNames`.
3. Use the listed `sqlName` values for columns, not display names with spaces.
4. Select only the columns needed.
5. Add `where`, `order by`, and `limit` clauses when possible.
6. Keep SQL read-only.

Moltsheet exposes each accessible sheet as a logical SQL table. Every table includes:

- `__row_id`: the Moltsheet row UUID
- `__row_order`: the sheet row order
- Sheet columns using sanitized SQL identifiers

Example filtered projection:

```bash
moltsheet sql query --query "select company, ceo_name from sidewalk_robotics_companies_top_50 where company ilike '%robot%' order by __row_order limit 10" --json
```

Example aggregate:

```bash
moltsheet sql query --query "select commented, count(*)::int as total from linkedin_posts_20260223_023644 group by commented" --json
```

Example join across accessible sheets:

```bash
moltsheet sql query --query "select a.company, b.post_url from sidewalk_robotics_companies_top_50 a cross join linkedin_posts_20260223_023644 b limit 5" --json
```

SQL safety model:

- Queries can only reference sheets the current API key owns or can read as a collaborator.
- SQL is read-only `SELECT` only.
- Raw base tables such as `agents`, `sheets`, `rows`, `cells`, `columns`, and `collaborators` are not available.
- DML, DDL, multiple statements, schema-qualified table names, unsafe functions, unknown tables, and CTE shadowing are rejected.
- Results are capped by the server; use `--limit` to request a smaller cap.
- `read` and `write` collaborators can query shared sheets, but SQL never grants write access.

Update a sheet:

```bash
moltsheet sheet update SHEET_ID --name "Leads v2" --json
```

Update a schema and allow destructive changes:

```bash
cat schema.json | moltsheet sheet update SHEET_ID --schema-stdin --confirm-data-loss --json
```

Delete a sheet:

```bash
moltsheet sheet delete SHEET_ID --json
```

Create a sheet from schema stdin:

```bash
cat schema.json | moltsheet sheet create "Leads" --schema-stdin --json
```

Create empty rows:

```bash
moltsheet row add SHEET_ID --count 10 --json
```

Add one row from stdin:

```bash
cat row.json | moltsheet row add SHEET_ID --data-stdin --json
```

Import multiple rows:

```bash
cat rows.json | moltsheet row import SHEET_ID --stdin --json
```

Import multiple JSON rows through the dedicated sheet import route:

```bash
cat rows.json | moltsheet sheet import SHEET_ID --stdin --json
```

Import a CSV file into an existing sheet:

```bash
moltsheet sheet import SHEET_ID --csv-file data.csv --json
```

Import CSV from stdin:

```bash
cat data.csv | moltsheet sheet import SHEET_ID --csv-stdin --json
```

Large JSON and CSV imports are batched automatically by the CLI. Use `--batch-size` only when you need smaller server requests:

```bash
moltsheet sheet import SHEET_ID --csv-file data.csv --batch-size 500 --json
```

CSV import rules:

- The target sheet must already exist
- The first CSV row must contain column headers
- CSV headers must exactly match existing sheet column names
- Unknown CSV headers fail before rows are imported
- Missing sheet columns are imported as empty values
- Do not convert large CSV files into one huge JSON payload; use `--csv-file` or `--csv-stdin`

List rows:

```bash
moltsheet row list SHEET_ID --json
```

Delete rows by ID:

```bash
cat row-ids.json | moltsheet row delete SHEET_ID --stdin --json
```

Delete one row by index:

```bash
moltsheet row delete-index SHEET_ID 0 --json
```

Update cells:

```bash
cat updates.json | moltsheet cell update SHEET_ID --stdin --json
```

Add columns:

```bash
cat columns.json | moltsheet column add SHEET_ID --stdin --json
```

Delete columns by index list:

```bash
cat indices.json | moltsheet column delete SHEET_ID --stdin --json
```

Delete one column by index:

```bash
moltsheet column delete-index SHEET_ID 1 --json
```

Rename a column:

```bash
moltsheet column rename SHEET_ID 0 --name "Company Name" --json
```

Share a sheet:

```bash
moltsheet share add SHEET_ID --slug analyst.bot --access write --json
```

List collaborators:

```bash
moltsheet share list SHEET_ID --json
```

Remove a collaborator:

```bash
moltsheet share remove SHEET_ID --slug analyst.bot --json
```

## Structured Input Patterns

Prefer files or stdin for anything shaped like JSON.

Sheet schema example:

```json
[
  { "name": "Company", "type": "string" },
  { "name": "Website", "type": "url" },
  { "name": "Qualified", "type": "boolean" }
]
```

Single row example:

```json
{
  "Company": "Moltsheet",
  "Website": "https://www.moltsheet.com",
  "Qualified": true
}
```

Multiple rows example:

```json
[
  {
    "Company": "Moltsheet",
    "Website": "https://www.moltsheet.com",
    "Qualified": true
  },
  {
    "Company": "Example",
    "Website": "https://example.com",
    "Qualified": false
  }
]
```

Column definitions example:

```json
[
  { "name": "Company", "type": "string" },
  { "name": "Website", "type": "url" }
]
```

Row ID list example:

```json
[
  "123e4567-e89b-12d3-a456-426614174000",
  "123e4567-e89b-12d3-a456-426614174001"
]
```

Column index list example:

```json
[
  0,
  2
]
```

Cell updates example:

```json
[
  {
    "rowId": "123e4567-e89b-12d3-a456-426614174000",
    "column": "Qualified",
    "value": true
  }
]
```

## How Agents Should Handle the CLI

Use this operating style:

- Prefer `--json` for machine-readable output
- Read before writing: use `sheet list` or `sheet get` before mutating data
- Trust schema types and let the CLI or API validation guide corrections
- Prefer stdin or files over complex shell escaping
- Reuse stored auth rather than passing secrets repeatedly
- Use collaborator slugs for sharing, never API keys
- Use `sheet import` for the dedicated sheet import route and `row import` for rows-endpoint bulk insert behavior
- Use `sheet import --csv-file` or `--csv-stdin` for CSV files instead of converting large CSVs to JSON
- Let the CLI batch large CSV and JSON imports automatically; lower `--batch-size` if the server asks for smaller batches
- Use `sql query` for filtered/projection reads so you avoid fetching full rows when only selected columns or matching rows are needed
- If a command fails, inspect the error payload before retrying

Recommended write workflow:

1. Run `moltsheet auth status --json`
2. Run `moltsheet whoami --json`
3. Run `moltsheet sheet list --json`
4. Run `moltsheet sheet get SHEET_ID --json`
5. Confirm column names and expected types
6. Prepare JSON input
7. Run the write command with `--json`
8. Re-run `sheet get` or `sheet list` to verify the result

## Output and Validation

Supported schema types:

- `string`
- `number`
- `boolean`
- `date`
- `url`

Validation behavior:

- Empty values are allowed
- Invalid types return an error
- Bulk row imports reject the full request if any row is invalid
- Cell updates require valid `rowId` values and valid column names

Important note:

- Returned row values are stored and returned as strings, even when validated against number, boolean, date, or url schema types

## Agentic Import Error Handling

Import errors are designed to tell an agent what to do next. In `--json` mode, inspect:

- `error.code` - stable machine-readable failure code
- `error.message` - what failed
- `error.action` - the adjustment to make before retrying
- `error.retryable` - whether retrying without changing input may help
- `error.batch` and `error.rowRange` - which batch or source rows failed
- `error.column` - the relevant column when validation fails

Common adjustments:

- `unknown_csv_headers`: rename CSV headers to match sheet columns exactly, or update the sheet schema first
- `type_validation_failed`: fix the listed row and column value to match the sheet type
- `batch_too_large` or server payload errors: rerun with a smaller `--batch-size`
- `schema_lookup_failed`: verify authentication, sheet ID, and access before retrying

After correcting schema or data issues, rerun the same source import command. Previously successful batches remain committed; the failed batch writes zero rows.

## Collaboration Model

- Sheets are shared by agent slug
- Access levels are `read` and `write`
- API keys are never exposed through collaboration commands
- Collaboration responses expose only `slug` and `displayName`

## Troubleshooting

If `moltsheet` is not installed:

```bash
npx moltsheet@latest sheet list --json
```

If you suspect auth problems:

```bash
moltsheet auth status --json
moltsheet whoami --json
```

If you need to bypass stored auth for one call:

```bash
moltsheet sheet list --api-key YOUR_API_KEY --json
```

If you are working inside the repo and the published CLI is unavailable:

```bash
npm run cli -- sheet list --json
```

## HTTP Fallback

Use raw HTTP only if you cannot run the CLI.

Base URL:

```bash
https://www.moltsheet.com/api/v1
```

Example list sheets request:

```bash
curl https://www.moltsheet.com/api/v1/sheets \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example create sheet request:

```bash
curl -X POST https://www.moltsheet.com/api/v1/sheets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Leads",
    "description": "Outbound leads",
    "schema": [
      { "name": "Company", "type": "string" },
      { "name": "Website", "type": "url" }
    ]
  }'
```

Example SQL tables request:

```bash
curl https://www.moltsheet.com/api/v1/sql/tables \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example SQL query request:

```bash
curl -X POST https://www.moltsheet.com/api/v1/sql/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "select company, website from leads where qualified = true limit 10",
    "limit": 100
  }'
```

## Short Rules For Agents

- Prefer the CLI over `curl`
- Prefer `--json`
- Prefer files or stdin for structured payloads
- Read the sheet schema before writing
- Use SQL for read-only filtered data retrieval, selected columns, joins, and aggregates
- Verify writes by reading the sheet again
- Use `npx moltsheet@latest` when the binary is not installed

don't have the plugin yet? install it then click "run inline in claude" again.

Moltsheet

Moltsheet is a spreadsheet API for AI agents with a CLI designed to be easier and safer for agents than handwritten HTTP requests.

intent

Use Moltsheet when you need to create sheets, inspect data, query filtered data, import rows, update cells, or share sheets with another agent. Prefer the CLI over raw HTTP because it handles auth once, validates JSON safely, batches large imports, and exposes structured error codes that tell you exactly what to fix before retrying. Use this skill whenever Codex needs spreadsheet-style data access, filtered reads, selected columns, joins, aggregates, or mutations.

inputs

CLI Installation

moltsheet binary via npm install -g moltsheet (preferred)
Or npx moltsheet@latest for one-off usage without global install
Or local build from Moltsheet repo via npm run cli -- (if working inside the repo)

Authentication

MOLTSHEET_API_KEY environment variable (optional, takes precedence over stored credential)
--api-key YOUR_API_KEY flag (overrides all other auth methods)
Stored local credential from moltsheet auth login (falls back if env var and flag absent)
Credential storage via keytar on macOS (Keychain), Windows (Credential Manager), Linux (Secret Service or libsecret), or local config file if secure storage unavailable
Production endpoint: https://www.moltsheet.com

Sheet and Data Inputs

Sheet ID (UUID returned by create or list commands)
Agent slug (e.g. research.bot) for sharing and identification
Schema JSON: array of column definitions with name and type fields
Row data: JSON objects or arrays matching sheet schema
CSV files with headers matching sheet column names exactly
SQL queries (read-only SELECT only, no DML, DDL, CTEs, or schema-qualified names)
Cell updates: JSON array with rowId, column, and value fields
Row IDs: UUIDs from __row_id field
Column indices: zero-based integers

Supported Schema Types

string
number
boolean
date
url

External Connections

Moltsheet API at https://www.moltsheet.com/api/v1 (no OAuth required, bearer token auth only)

procedure

1. Confirm CLI availability

Input: none Run: moltsheet --version Output: version string or "command not found" Decision: if not found, proceed to step 2; if found, skip to step 3.

2. Install or use via npx

Input: Node.js 14+ (required) If installing globally:

Run: npm install -g moltsheet
Output: success message, moltsheet available in PATH

If using one-off:

Replace all moltsheet with npx moltsheet@latest in commands below

If working inside repo:

Run: npm --prefix cli install && npm run build:cli
Replace all moltsheet with npm run cli -- in commands below

3. Authenticate once

Input: none (if API key already in env var or stored) or API key string Run one of:

moltsheet auth login (interactive, stores credential securely)
moltsheet auth login --api-key YOUR_API_KEY (non-interactive)
Set MOLTSHEET_API_KEY env var and skip this step

Output: confirmation message or stored credential confirmation Next: proceed to step 4.

4. Verify agent identity

Input: stored or env var authentication from step 3 Run: moltsheet whoami --json Output: JSON object with agentId, slug, displayName (no API key exposed) Decision: if agentId is empty or error occurs, auth failed; re-run step 3. Otherwise, proceed to step 5.

5. List accessible sheets (optional, recommended before mutations)

Input: authentication from step 3 Run: moltsheet sheet list --json Output: JSON array of sheet objects with id, name, description, columnCount, rowCount, createdAt Decision: if you need to inspect one sheet, proceed to step 6; if creating new sheet, jump to step 7a; if querying, jump to step 8a.

6. Inspect target sheet schema

Input: sheet ID from step 5 or provided externally Run: moltsheet sheet get SHEET_ID --json Output: JSON object with id, name, schema (array of column definitions with name, type, index), columnCount, rowCount Decision: compare schema to your data format. If schema matches your data, proceed to mutations (step 9-12). If schema needs changes, run column operations (step 13-15) first. If you need filtered read, jump to step 8b.

7a. Create new sheet from schema

Input: sheet name string and schema JSON (array of column definitions) Prepare schema file (e.g. schema.json):

[
  { "name": "Company", "type": "string" },
  { "name": "Website", "type": "url" },
  { "name": "Qualified", "type": "boolean" }
]

Run: cat schema.json | moltsheet sheet create "Sheet Name" --schema-stdin --json Output: JSON object with newly created sheet id, name, schema, columnCount, rowCount Next: proceed to import/mutation steps (9-12) or skip if sheet-only operation.

7b. Create empty sheet (no schema)

Input: sheet name string Run: moltsheet sheet create "Sheet Name" --json Output: JSON object with sheet id, name, empty schema array Next: add columns via step 13 or import rows.

8a. Query accessible tables

Input: authentication from step 3 Run: moltsheet sql tables --json Output: JSON array of table objects with displayName, sqlName, sqlNames (array of available column names) Decision: save sqlName and sqlNames for step 8b query construction.

8b. Run read-only SQL query

Input: table name from step 8a, query string, optional limit parameter Prepare query file or use stdin:

select company, ceo_name from sidewalk_robotics_companies_top_50
where company ilike '%robot%'
order by __row_order
limit 10

Run one of:

moltsheet sql query --query "SELECT ..." --json
cat query.sql | moltsheet sql query --stdin --limit 500 --json
moltsheet sql query --file query.sql --limit 100 --json

Output: JSON object with rows (array of result objects), rowCount, executionTimeMs Next: process results or return to step 6 if need full sheet write.

9a. Add empty rows

Input: sheet ID, count of rows to create Run: moltsheet row add SHEET_ID --count 10 --json Output: JSON object with rowIds (array of new row UUIDs), count Next: skip to step 12 (cell update) if filling specific cells, or stop if rows-only operation.

9b. Add single row from data

Input: sheet ID, row data JSON object matching schema Prepare row file or use stdin:

{
  "Company": "Moltsheet",
  "Website": "https://www.moltsheet.com",
  "Qualified": true
}

Run: cat row.json | moltsheet row add SHEET_ID --data-stdin --json Output: JSON object with rowIds (array with one UUID), count is 1 Next: proceed to step 12 if more updates needed, or stop.

10a. Import multiple rows (rows endpoint)

Input: sheet ID, row data JSON array Prepare rows file or use stdin:

[
  { "Company": "A", "Website": "https://a.com", "Qualified": true },
  { "Company": "B", "Website": "https://b.com", "Qualified": false }
]

Run: cat rows.json | moltsheet row import SHEET_ID --stdin --json Output: JSON object with import summary, successCount, failureCount, error list if any rows failed Decision: if failureCount > 0, inspect error.code, error.message, error.action, fix source data, rerun with same source file. Otherwise, proceed to step 11.

10b. Import CSV file into existing sheet

Input: sheet ID, CSV file with headers matching sheet column names exactly Prepare CSV file (e.g. data.csv):

Company,Website,Qualified
Moltsheet,https://www.moltsheet.com,true
Example,https://example.com,false

Run one of:

moltsheet sheet import SHEET_ID --csv-file data.csv --json
cat data.csv | moltsheet sheet import SHEET_ID --csv-stdin --json
For large CSV, control batch size: moltsheet sheet import SHEET_ID --csv-file data.csv --batch-size 500 --json

Output: JSON object with import summary, successCount, failureCount, optional error list Decision: if failureCount > 0, inspect error for schema mismatch or type validation failure, fix CSV or sheet schema, rerun. Otherwise, proceed to step 11.

10c. Import JSON rows (dedicated sheet endpoint)

Input: sheet ID, row data JSON array Prepare rows file (same format as 10a):

Run: cat rows.json | moltsheet sheet import SHEET_ID --stdin --json Output: same as 10a Decision: same as 10a.

11. Verify import success

Input: sheet ID from step 10 Run: moltsheet sheet get SHEET_ID --json or moltsheet row list SHEET_ID --json Output: updated rowCount, or list of rows with id, values, order Decision: if counts match expected, import succeeded. Otherwise, inspect error from step 10 and retry.

12. Update specific cells

Input: sheet ID, cell updates JSON array with rowId, column, value Prepare updates file or use stdin:

[
  {
    "rowId": "123e4567-e89b-12d3-a456-426614174000",
    "column": "Qualified",
    "value": true
  },
  {
    "rowId": "123e4567-e89b-12d3-a456-426614174001",
    "column": "Company",
    "value": "NewCompany"
  }
]

Run: cat updates.json | moltsheet cell update SHEET_ID --stdin --json Output: JSON object with updatedCount, failureCount, optional error list Decision: if failureCount > 0, inspect errors for invalid rowId or unknown column, fix and rerun. Otherwise, proceed to verification.

13. Add columns

Input: sheet ID, column definitions JSON array Prepare columns file:

[
  { "name": "Industry", "type": "string" },
  { "name": "EmployeeCount", "type": "number" }
]

Run: cat columns.json | moltsheet column add SHEET_ID --stdin --json Output: JSON object with new schema, columnCount Next: proceed to data operations or mutations.

14. Rename column

Input: sheet ID, zero-based column index, new name string Run: moltsheet column rename SHEET_ID 0 --name "Company Name" --json Output: JSON object with updated schema, columnCount Next: verify rename via step 6.

15. Delete columns

Input: sheet ID, column indices JSON array Prepare indices file or use single column:

[0, 2]

Run one of:

cat indices.json | moltsheet column delete SHEET_ID --stdin --json (multiple columns)
moltsheet column delete-index SHEET_ID 1 --json (single column)

Output: JSON object with updated schema, columnCount Decision: if data loss warning shown, confirm operation is intentional. Otherwise, proceed to verification.

16. Delete rows

Input: sheet ID, row IDs JSON array or single row index Prepare row IDs file or use single index:

[
  "123e4567-e89b-12d3-a456-426614174000",
  "123e4567-e89b-12d3-a456-426614174001"
]

Run one of:

cat row-ids.json | moltsheet row delete SHEET_ID --stdin --json (by UUID)
moltsheet row delete-index SHEET_ID 0 --json (by zero-based index)

Output: JSON object with deletedCount, failureCount Next: verify via step 11.

17. Share sheet with another agent

Input: sheet ID, target agent slug (e.g. analyst.bot), access level (read or write) Run: moltsheet share add SHEET_ID --slug analyst.bot --access write --json Output: JSON object with collaborator slug, displayName, access level Next: verify via step 18.

18. List sheet collaborators

Input: sheet ID Run: moltsheet share list SHEET_ID --json Output: JSON array of collaborator objects with slug, displayName, access Decision: verify target agent slug appears with correct access level.

19. Remove collaborator

Input: sheet ID, agent slug Run: moltsheet share remove SHEET_ID --slug analyst.bot --json Output: JSON object with confirmation message Next: verify via step 18.

20. Update sheet metadata

Input: sheet ID, new name or description string Run one of:

moltsheet sheet update SHEET_ID --name "Leads v2" --json (rename)
moltsheet sheet update SHEET_ID --description "Updated description" --json (change description)

Output: JSON object with updated sheet metadata Next: verify via step 6.

21. Update sheet schema (destructive)

Input: sheet ID, new schema JSON, confirmation flag Prepare new schema file:

Run: cat schema.json | moltsheet sheet update SHEET_ID --schema-stdin --confirm-data-loss --json Output: JSON object with updated schema, columnCount Decision: use only when intentionally removing columns or changing types. Ensure --confirm-data-loss present to prevent accidental loss.

22. Delete entire sheet

Input: sheet ID Run: moltsheet sheet delete SHEET_ID --json Output: JSON object with confirmation message including sheet ID Decision: use only when sheet no longer needed. No recovery possible.

decision points

Auth method selection (step 3)

If MOLTSHEET_API_KEY env var is set:

Skip moltsheet auth login, use env var directly

If API key available as string but not in env var:

Use moltsheet auth login --api-key YOUR_API_KEY (non-interactive, faster for agents)

If no API key and no prior auth login:

Use moltsheet auth login (interactive, stores credential securely for future calls)

If stored credential exists but you need to override:

Pass --api-key YOUR_API_KEY flag on any command

CLI availability (step 2)

If moltsheet binary not found:

Use npx moltsheet@latest instead (requires Node.js 14+ in PATH)

If npx unavailable:

Install globally: npm install -g moltsheet

If inside Moltsheet repository:

Use npm run cli -- instead of moltsheet

Sheet operation selection (step 5)

If you need to create a new sheet:

Jump to step 7a (schema-driven) or 7b (empty)

If you need to read filtered data:

Jump to step 8a and 8b (SQL query)

If you need to inspect existing sheet:

Jump to step 6 (get schema)

If you need to import data:

Jump to step 10a, 10b, or 10c depending on data format (JSON rows, CSV, or sheet endpoint)

Write workflow validation (step 6 to mutations)

Before any data mutation:

Always run moltsheet sheet get SHEET_ID --json to confirm column names and types

If schema does not match your data:

Use steps 13-15 to add, rename, or delete columns first

If schema matches but row data is in wrong format:

Fix row JSON structure, do not skip schema check

Import route selection (step 10)

If importing JSON rows to rows endpoint:

Use step 10a (row import)

If importing JSON rows to sheet endpoint (supports batching and automatic retry):

Use step 10c (sheet import)

If importing CSV file:

Use step 10b (sheet import --csv-file or --csv-stdin)

If CSV file is larger than 100,000 rows:

Use --batch-size 500 to control server request size

Import error handling (step 10 decision)

If failureCount > 0:

Inspect error.code (e.g. unknown_csv_headers, type_validation_failed, batch_too_large)
Inspect error.action for exact fix required
If error.retryable is true, fix input and rerun same command
If error.retryable is false, fix schema or data source, then rerun
Previously successful batches remain committed; only failed batch writes zero rows

If error.code is unknown_csv_headers:

Rename CSV headers to match sheet column names exactly, or update sheet schema first via steps

Moltsheet - Spreadsheets for AI agents

related skills

Moltsheet

intent

inputs

procedure

decision points