KosmoKrator

productivity

Grist CLI for AI Agents

Use the Grist CLI from KosmoKrator to call Grist tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

13 functions 9 read 4 write API key auth
Submit Grist feedback View package source

Grist CLI Setup

Grist can be configured headlessly with `kosmokrator integrations:configure grist`.

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure grist --set api_key="$GRIST_API_KEY" --set base_url="$GRIST_BASE_URL" --enable --read allow --write ask --json
kosmokrator integrations:doctor grist --json
kosmokrator integrations:status --json

Credentials

Authentication type: API key api_key. Configure credentials once, then use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

KeyEnv varTypeRequiredLabel
api_key GRIST_API_KEY Secret secret yes API Key
base_url GRIST_BASE_URL Text string yes Base URL

Call Grist Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

kosmo integrations:call grist.grist_list_workspaces '{
  "org_id": 1
}' --json

Use the provider shortcut form for shorter human-facing commands.

kosmo integrations:grist grist_list_workspaces '{
  "org_id": 1
}' --json

Agent Discovery Commands

These commands return structured output for coding agents that need to inspect capabilities before choosing a function. 

kosmo integrations:docs grist --json
kosmo integrations:docs grist.grist_list_workspaces --json
kosmo integrations:schema grist.grist_list_workspaces --json
kosmo integrations:search "Grist" --json
kosmo integrations:list --json

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Grist.

grist.grist_list_workspaces

Read read

List all workspaces in a Grist organization.

Parameters
org_id

Generic CLI call

kosmo integrations:call grist.grist_list_workspaces '{"org_id":1}' --json

Provider shortcut

kosmo integrations:grist grist_list_workspaces '{"org_id":1}' --json

grist.grist_get_workspace

Read read

Get details for a single Grist workspace, including its documents.

Parameters
workspace_id

Generic CLI call

kosmo integrations:call grist.grist_get_workspace '{"workspace_id":1}' --json

Provider shortcut

kosmo integrations:grist grist_get_workspace '{"workspace_id":1}' --json

grist.grist_list_docs

Read read

List all documents in a Grist organization.

Parameters
org_id

Generic CLI call

kosmo integrations:call grist.grist_list_docs '{"org_id":1}' --json

Provider shortcut

kosmo integrations:grist grist_list_docs '{"org_id":1}' --json

grist.grist_get_doc

Read read

Get details for a single Grist document by ID.

Parameters
doc_id

Generic CLI call

kosmo integrations:call grist.grist_get_doc '{"doc_id":"example_doc_id"}' --json

Provider shortcut

kosmo integrations:grist grist_get_doc '{"doc_id":"example_doc_id"}' --json

grist.grist_list_tables

Read read

List all tables in a Grist document.

Parameters
doc_id

Generic CLI call

kosmo integrations:call grist.grist_list_tables '{"doc_id":"example_doc_id"}' --json

Provider shortcut

kosmo integrations:grist grist_list_tables '{"doc_id":"example_doc_id"}' --json

grist.grist_get_table

Read read

Get a single table from a Grist document.

Parameters
doc_id, table_id

Generic CLI call

kosmo integrations:call grist.grist_get_table '{"doc_id":"example_doc_id","table_id":"example_table_id"}' --json

Provider shortcut

kosmo integrations:grist grist_get_table '{"doc_id":"example_doc_id","table_id":"example_table_id"}' --json

grist.grist_list_records

Read read

List records from a Grist table with optional filtering, sorting, and limiting.

Parameters
doc_id, table_id, limit, sort, filter

Generic CLI call

kosmo integrations:call grist.grist_list_records '{"doc_id":"example_doc_id","table_id":"example_table_id","limit":1,"sort":"example_sort","filter":"example_filter"}' --json

Provider shortcut

kosmo integrations:grist grist_list_records '{"doc_id":"example_doc_id","table_id":"example_table_id","limit":1,"sort":"example_sort","filter":"example_filter"}' --json

grist.grist_get_record

Read read

Get full column data for a Grist table (raw cell values per column).

Parameters
doc_id, table_id

Generic CLI call

kosmo integrations:call grist.grist_get_record '{"doc_id":"example_doc_id","table_id":"example_table_id"}' --json

Provider shortcut

kosmo integrations:grist grist_get_record '{"doc_id":"example_doc_id","table_id":"example_table_id"}' --json

grist.grist_create_records

Write write

Create one or more records in a Grist table.

Parameters
doc_id, table_id, records

Generic CLI call

kosmo integrations:call grist.grist_create_records '{"doc_id":"example_doc_id","table_id":"example_table_id","records":"example_records"}' --json

Provider shortcut

kosmo integrations:grist grist_create_records '{"doc_id":"example_doc_id","table_id":"example_table_id","records":"example_records"}' --json

grist.grist_update_records

Write write

Update one or more existing records in a Grist table.

Parameters
doc_id, table_id, records

Generic CLI call

kosmo integrations:call grist.grist_update_records '{"doc_id":"example_doc_id","table_id":"example_table_id","records":"example_records"}' --json

Provider shortcut

kosmo integrations:grist grist_update_records '{"doc_id":"example_doc_id","table_id":"example_table_id","records":"example_records"}' --json

grist.grist_delete_records

Write write

Delete records from a Grist table by row IDs.

Parameters
doc_id, table_id, record_ids

Generic CLI call

kosmo integrations:call grist.grist_delete_records '{"doc_id":"example_doc_id","table_id":"example_table_id","record_ids":"example_record_ids"}' --json

Provider shortcut

kosmo integrations:grist grist_delete_records '{"doc_id":"example_doc_id","table_id":"example_table_id","record_ids":"example_record_ids"}' --json

grist.grist_create_column

Write write

Create a new column in a Grist table.

Parameters
doc_id, table_id, col_id, label, type, formula

Generic CLI call

kosmo integrations:call grist.grist_create_column '{"doc_id":"example_doc_id","table_id":"example_table_id","col_id":"example_col_id","label":"example_label","type":"example_type","formula":"example_formula"}' --json

Provider shortcut

kosmo integrations:grist grist_create_column '{"doc_id":"example_doc_id","table_id":"example_table_id","col_id":"example_col_id","label":"example_label","type":"example_type","formula":"example_formula"}' --json

grist.grist_list_columns

Read read

List all columns in a Grist table.

Parameters
doc_id, table_id

Generic CLI call

kosmo integrations:call grist.grist_list_columns '{"doc_id":"example_doc_id","table_id":"example_table_id"}' --json

Provider shortcut

kosmo integrations:grist grist_list_columns '{"doc_id":"example_doc_id","table_id":"example_table_id"}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

grist.grist_list_workspaces

List all workspaces in a Grist organization.

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_list_workspaces --json
ParameterTypeRequiredDescription
org_id integer yes Grist organization ID.

grist.grist_get_workspace

Get details for a single Grist workspace, including its documents.

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_get_workspace --json
ParameterTypeRequiredDescription
workspace_id integer yes Grist workspace ID.

grist.grist_list_docs

List all documents in a Grist organization.

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_list_docs --json
ParameterTypeRequiredDescription
org_id integer yes Grist organization ID.

grist.grist_get_doc

Get details for a single Grist document by ID.

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_get_doc --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.

grist.grist_list_tables

List all tables in a Grist document.

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_list_tables --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.

grist.grist_get_table

Get a single table from a Grist document.

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_get_table --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.
table_id string yes Grist table ID.

grist.grist_list_records

List records from a Grist table with optional filtering, sorting, and limiting.

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_list_records --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.
table_id string yes Grist table ID.
limit integer no Maximum number of records to return.
sort string no Sort expression, e.g. "Col1" (ascending) or "-Col1" (descending).
filter string no JSON object for column filtering, e.g. {"Col1": ["val1", "val2"]}.

grist.grist_get_record

Get full column data for a Grist table (raw cell values per column).

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_get_record --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.
table_id string yes Grist table ID.

grist.grist_create_records

Create one or more records in a Grist table.

Operation
Write write
Schema command
kosmo integrations:schema grist.grist_create_records --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.
table_id string yes Grist table ID.
records string yes JSON array of record objects, each with a "fields" key (e.g., [{"fields":{"Col1":"val","Col2":42}}]).

grist.grist_update_records

Update one or more existing records in a Grist table.

Operation
Write write
Schema command
kosmo integrations:schema grist.grist_update_records --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.
table_id string yes Grist table ID.
records string yes JSON array of record updates, each with "id" and "fields" keys (e.g., [{"id":1,"fields":{"Col1":"new"}}]).

grist.grist_delete_records

Delete records from a Grist table by row IDs.

Operation
Write write
Schema command
kosmo integrations:schema grist.grist_delete_records --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.
table_id string yes Grist table ID.
record_ids string yes JSON array of row IDs to delete (e.g., [1, 2, 3]).

grist.grist_create_column

Create a new column in a Grist table.

Operation
Write write
Schema command
kosmo integrations:schema grist.grist_create_column --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.
table_id string yes Grist table ID.
col_id string yes Column identifier (used as the field key, e.g., "FirstName").
label string yes Human-readable column label.
type string yes Grist column type (e.g., "Text", "Int", "Numeric", "Bool", "Date", "Choice", "Ref", "Any").
formula string no Optional formula for a formula column (e.g., "$A + $B").

grist.grist_list_columns

List all columns in a Grist table.

Operation
Read read
Schema command
kosmo integrations:schema grist.grist_list_columns --json
ParameterTypeRequiredDescription
doc_id string yes Grist document ID.
table_id string yes Grist table ID.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.