CodaCli
title: coda-cli radar_quadrant: Tools radar_ring: Trial radar_position: inner source_url: https://github.com/dennislwm/coda-cli
A bespoke Python CLI wrapping the Coda.io API, built to enable document and row management from the command line. The tool covers the full read surface of the Coda API and exposes row-level write operations, compensating for the API's fundamental constraint: table and column schema cannot be created or modified programmatically. Document structure must be established manually in the Coda UI before any CLI automation is applied.
The CLI operates against a live Coda API session authenticated via an API key. A template registry layer decouples human-readable names from raw Coda document IDs, allowing commands to accept either a template name or a raw ID. Commands that accept a document ID also resolve Coda browser URLs automatically.
The output surface supports four formats (text, CSV, JSON, markdown), selectable at invocation time. Output goes to stdout by default; file output is available on export commands. There is no offline cache — every command makes a live API call.
Write operations implement API-aware safeguards: batch upserts send rows in groups of up to 500 per request and self-throttle to stay within the Coda API write rate limit. The upsert-rows command supports optional key-column deduplication; omitting key columns inserts all rows unconditionally.
A new user authenticates by setting an API key and running the auth verification command to confirm access. All commands are exposed as Make targets; the user interacts through make <command> rather than invoking the Python entrypoint directly. Explore commands pipe output through jq by default, producing formatted JSON for inspection.
The user explores their workspace by listing documents, inspects a document's structure by listing its sections, tables, and columns, and queries rows from a specific table. For recurring access, the user registers a template name mapped to a frequently-used document ID, eliminating the need to look up raw IDs in subsequent commands.
For document templating, the user exports an existing document's structure as a YAML template file. On import, runtime variables can be substituted into the template, allowing a single template to produce documents with different names or values. The resulting document shell is created in Coda, but table and column structure must be established manually in the UI before row operations can proceed.
For bulk data workflows, the user prepares a CSV file and runs a bulk upsert against an existing table. The CLI handles pagination, batching, and rate limiting transparently; the user receives a summary of rows inserted and updated on completion.
The CLI runs locally via Pipenv or inside a Docker container. Both paths are supported through Make targets; the Docker path is the distribution model for environments without a local Python setup.
The CLI covers three tiers of the Coda data model. Read commands span the full document hierarchy: documents, sections, tables, columns, rows, and structural elements (views, formulas, controls, folders). Write commands are scoped to row-level operations: single-row insert, update, upsert, delete, and bulk upsert from CSV. Template commands manage the name registry and support round-trip export and import of document structure as YAML with variable substitution. An authentication verification command confirms API key validity before any substantive operation.
The Coda API v1 supports document creation — a new document shell can be provisioned programmatically, subject to the API token owner holding Doc Maker or Admin role in the workspace. However, the API exposes no endpoints for creating or modifying tables or columns. The import-template command explicitly does not attempt schema creation — templates carry structural metadata for documentation purposes only. Any document scaffold requiring new tables or columns must be prepared in the Coda UI first.
This means full document-as-code (create document and provision schema in one automated flow) is blocked. Partial document-as-code (create document shell, then populate rows) is supported. The CD pipeline described in the project documentation is blocked specifically by the schema ceiling, not by document creation itself. This constraint is permanent for the current API version and defines the automation ceiling of the CLI regardless of implementation quality.
The project has a functioning CI pipeline (CircleCI), Docker image distribution via Docker Hub, a Plumber-maintained spec-test-code sync, and seven distinct test modules covering major command groups. The spec in doc/spec.md documents all implemented behaviour including API constraints and rate limits. Recent commits indicate active development through early 2026.
Against this, several maturity gaps remain. Dependencies are pinned to 2022-era versions (Click 8.1.3, codaio 0.6.10); the codaio library is a third-party wrapper with its own maintenance dependency. The CircleCI configuration references an outdated Docker version that causes build failures on the apt-get layer — a known documented issue with a known fix not yet applied.
The CLI is not designed for autonomous agent consumption. There are no typed exit codes, no compact output mode, and no offline index. Every query requires a live network call.
CLIPrintingPress would generate a Go CLI from the Coda OpenAPI spec (publicly available), producing agent-native output (typed exit codes, compact mode, auto-JSON when piped) and a local SQLite cache with FTS5 search for read-heavy query patterns. The generation approach would also absorb features from competing Coda CLI tools automatically.
The trade-off is scope: CLI Printing Press generates the read and row-write surface well, but the bespoke coda-cli adds value that generation cannot replicate — the template registry, the YAML round-trip export/import with variable substitution, the API-aware rate-limiting in upsert-rows, and the Plumber-backed spec. These are deliberate design decisions, not gaps a generator would fill.
The two are not mutually exclusive. A generated CLI would serve agent-consumption patterns more effectively; the bespoke CLI retains value for the template and bulk-write workflows. The API ceiling applies equally to both.
coda-cli is placed in Trial at inner position. The row-level write surface including bulk upsert with rate limiting and the template registry are confirmed in production use, clearing the Trial gate. The outdated CI Docker version and pinned 2022 dependencies are the primary readiness gaps before Adopt. The schema ceiling and partial CD pipeline blockage are permanent API constraints, not quality indicators.
