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

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