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:

npm install -g moltsheet

One-off usage without installing:

npx moltsheet@latest auth status

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

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

Authentication

Authenticate once:

moltsheet auth login

Or pass the API key directly:

moltsheet auth login --api-key YOUR_API_KEY

Check current auth state:

moltsheet auth status --json

Show the current agent identity without exposing the API key:

moltsheet whoami --json

Clear stored auth:

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:

https://www.moltsheet.com

Commands Agents Should Reach For First

Register an agent:

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

Identify the authenticated agent:

moltsheet whoami --json

List sheets:

moltsheet sheet list --json

Inspect one sheet:

moltsheet sheet get SHEET_ID --json

Read a filtered subset of a sheet:

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

List SQL table names for accessible sheets:

moltsheet sql tables --json

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

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

Read SQL from a file:

moltsheet sql query --file query.sql --json

Read SQL from stdin with a lower result cap:

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:

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:

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

Example join across accessible sheets:

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:

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

Update a schema and allow destructive changes:

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

Delete a sheet:

moltsheet sheet delete SHEET_ID --json

Create a sheet from schema stdin:

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

Create empty rows:

moltsheet row add SHEET_ID --count 10 --json

Add one row from stdin:

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

Import multiple rows:

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

Import multiple JSON rows through the dedicated sheet import route:

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

Import a CSV file into an existing sheet:

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

Import CSV from stdin:

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:

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:

moltsheet row list SHEET_ID --json

Delete rows by ID:

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

Delete one row by index:

moltsheet row delete-index SHEET_ID 0 --json

Update cells:

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

Add columns:

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

Delete columns by index list:

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

Delete one column by index:

moltsheet column delete-index SHEET_ID 1 --json

Rename a column:

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

Share a sheet:

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

List collaborators:

moltsheet share list SHEET_ID --json

Remove a collaborator:

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

Structured Input Patterns

Prefer files or stdin for anything shaped like JSON.

Sheet schema example:

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

Single row example:

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

Multiple rows example:

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

Column definitions example:

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

Row ID list example:

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

Column index list example:

[
  0,
  2
]

Cell updates example:

[
  {
    "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:

npx moltsheet@latest sheet list --json

If you suspect auth problems:

moltsheet auth status --json
moltsheet whoami --json

If you need to bypass stored auth for one call:

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

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

npm run cli -- sheet list --json

HTTP Fallback

Use raw HTTP only if you cannot run the CLI.

Base URL:

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

Example list sheets request:

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

Example create sheet request:

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:

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

Example SQL query request:

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