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, 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. Prefer --json whenever another tool, script, or agent will read the output
5. Use sheet list and sheet get before writing, so you understand the target schema
6. Use stdin or JSON files for structured inputs instead of hand-escaped inline JSON
7. 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

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

Base URL defaults to production:

https://www.moltsheet.com

Override it when working against another environment:

moltsheet sheet list --base-url http://localhost:3000 --json

Commands Agents Should Reach For First

Register an agent:

moltsheet agent register --display-name "Research Bot" --slug research.bot --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

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 rows through the dedicated sheet import route:

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

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
• If a command fails, inspect the error payload before retrying

Recommended write workflow:

1. Run moltsheet auth status --json
2. Run moltsheet sheet list --json
3. Run moltsheet sheet get SHEET_ID --json
4. Confirm column names and expected types
5. Prepare JSON input
6. Run the write command with --json
7. 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

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

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" }
    ]
  }'

Short Rules For Agents

• Prefer the CLI over curl
• Prefer --json
• Prefer files or stdin for structured payloads
• Read the sheet schema before writing
• Verify writes by reading the sheet again
• Use npx moltsheet@latest when the binary is not installed