Moltsheet CLI

The official command-line client for Moltsheet, a spreadsheet API built for AI agents and automation workflows.

Use moltsheet when you want agents, scripts, or local tools to read and update structured sheet data without wiring raw HTTP calls, parsing spreadsheets, or giving an agent direct database access.

Install

npm install -g moltsheet

Run without installing:

npx moltsheet@latest --help

Requirements:

• Node.js 20 or newer
• A Moltsheet API key

Quickstart

Authenticate once:

moltsheet auth login
moltsheet whoami --json

List available sheets:

moltsheet sheet list --json

Inspect a sheet:

moltsheet sheet get SHEET_ID --json

Fetch only the fields and rows you need:

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

Run read-only SQL over accessible sheets:

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

What You Can Do

• Authenticate once and reuse credentials securely
• Confirm the current agent slug, display name, description, and creation date
• List, create, inspect, rename, and delete sheets
• Read filtered sheet data with selected columns
• Run safe read-only SQL for joins, aggregates, sorting, and projections
• Add empty rows or import JSON/CSV rows in bulk
• Update cells from JSON files or stdin
• Add, rename, and delete columns
• Share sheets with other agents using read or write access
• Use --json everywhere for reliable scripting

Read-Only SQL

Moltsheet exposes each accessible sheet as a logical SQL table. Use SQL when you need more than a simple sheet read: filtered projections, joins, counts, grouping, or sorting.

List SQL table and column names:

moltsheet sql tables --json

Query by table alias:

moltsheet sql query \
  --query "select company, website from leads where qualified = true order by company limit 25" \
  --json

Query from a file:

moltsheet sql query --file query.sql --limit 500 --json

SQL is intentionally constrained:

• Single SELECT statement only
• Results are capped by the server
• Only sheets you own or can read as a collaborator are visible
• Raw storage tables are not exposed
• Mutating SQL, DDL, unsafe functions, schema-qualified names, and unknown tables are rejected

Data Writes

Create rows:

moltsheet row add SHEET_ID --count 10 --json

Import rows from JSON:

moltsheet row import SHEET_ID --file rows.json --json

Import rows from CSV:

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

Large JSON and CSV imports are batched automatically. Use --batch-size when you need smaller requests:

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

CSV imports target an existing sheet. The first row must contain headers that exactly match sheet column names; unknown headers fail before rows are imported.

Update cells from JSON:

moltsheet cell update SHEET_ID --file updates.json --json

Example updates.json:

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

Authentication

Login interactively or pass a key directly:

moltsheet auth login
moltsheet auth login --api-key YOUR_API_KEY

Credential resolution order:

1. --api-key
2. MOLTSHEET_API_KEY
3. Stored local credential

The CLI uses OS credential storage when available, with a local config fallback if secure storage is unavailable.

Common Commands

moltsheet auth status --json
moltsheet whoami --json
moltsheet agent register --display-name "Research Bot" --slug research.bot --json
moltsheet sheet list --json
moltsheet sheet get SHEET_ID --json
moltsheet sheet create "Leads" --schema-file schema.json --json
moltsheet sheet import SHEET_ID --file rows.json --json
moltsheet sheet import SHEET_ID --csv-file data.csv --json
moltsheet sql tables --json
moltsheet sql query --query "select count(*)::int as total from leads" --json
moltsheet row add SHEET_ID --count 10 --json
moltsheet row import SHEET_ID --file rows.json --json
moltsheet cell update SHEET_ID --file updates.json --json
moltsheet column add SHEET_ID --file columns.json --json
moltsheet share add SHEET_ID --slug analyst.bot --access write --json

Agent-Friendly Defaults

For AI agents and automation:

• Prefer --json
• Use sql tables before sql query
• Read the sheet schema before writing
• Use files or stdin for structured payloads
• Use --csv-file or --csv-stdin for CSV; do not convert large CSVs to one huge JSON payload
• Inspect error.action in JSON failures, fix the stated schema/data/batch issue, then rerun
• Verify writes by reading the sheet again
• Share by agent slug, never by API key

Links

• Website: moltsheet.com
• Agent skill: moltsheet.com/SKILL.md
• Source: github.com/youssefbm2008/web_excel_for_agents
• Issues: GitHub Issues