tinycld CLI reference

The complete surface of the tinycld binary. For a task-oriented introduction — downloading it, logging in, and typical usage — see Command line tool.

This page documents the user-facing tinycld binary. It is unrelated to tinycld-pkg, the per-member developer tool that runs biome, tsc, and vitest, and to @tinycld/bootstrap, the scaffolder.

Global flags

Available on every command:

Without a TTY the tool disables color and never blocks on input, so no extra flags are needed to make it CI-safe.

Table output is column-aligned with a header row; CSV writes a header row then records; JSON is indented. JSON is a separate payload from the table, not a serialization of it — some commands deliberately expose more (or differently-named) fields than they print. Verify a command’s actual JSON before depending on a key.

Exit codes

0 on success, 1 on any error. There is no differentiated exit-code scheme — do not branch on specific non-zero values.

Errors are written to stderr as Error: <message>. Server-side failures render as server error (HTTP <status>): <server message>.

Core commands

Present in every build regardless of which packages the server has.

search accepts --pkg <slug> (repeatable), --not <terms>, and --limit <n>. It understands the same query grammar as the in-app palette: pkg: prefixes scope the search and a leading hyphen excludes a term. Quote the query so the shell passes it as one argument; a query beginning with a hyphen needs a -- separator first.

Counts and partial-result warnings go to stderr, keeping stdout a clean document under --json.

A bare host in auth login or context add is normalized to https://, except localhost, 127.0.0.1, and ::1, which get http://.

Drive

Every path argument also accepts id:<record-id> to bypass path resolution.

Mail

--body-file - reads the message body from stdin. Folder, label, star, and read-state changes write the caller’s own per-user thread state, so they never affect other members of a shared mailbox.

Boards

Present when the Boards package is installed. The column group also answers to columns, and card to cards. Every view command aliases show, every remove aliases rm and delete, and list aliases ls.

A <board> argument resolves by id, key, or name; a <sprint> by its number within the board, active, next, or id; a card <id> by id or key (OTTER-123). Dates are YYYY-MM-DD, or "YYYY-MM-DD HH:MM" for a due time. Mutating commands print nothing in table format — use --json or --output csv to get the written row back. Board membership and share links are read-only to the CLI — manage them in the app.

Contacts

Group alias: contact.

rm is a soft delete. list --trashed finds trashed contacts and edit --restore brings one back; --permanent is the only hard delete.

Calendar

Group alias: cal.

Reading a calendar requires membership in any role; writing requires owner or editor. calendar list’s ROLE column is the only advance indication of which you have.

Text and Calc

Each contributes one command. Both alias comments to comment.

--all includes resolved threads. --cell uses one-based A1 notation, and a new spreadsheet comment also needs --sheet <id> (the sheet’s id, e.g. sheet1) — a reply inherits its thread’s anchor and refuses both flags. Documents and workbooks are Drive items, so tinycld drive handles creating, listing, downloading, and deleting them; their bodies are collaborative edit operations with no safe shell representation, which is why only comments are exposed here.

Authentication and scopes

Login uses the OAuth 2.1 Device Authorization Grant (RFC 8628) against the first-party public client tinycld-cli. The CLI requests a device code, prints the user code, opens the browser for approval, and polls for the token.

Access tokens refresh automatically when a request returns 401. A revoked or expired refresh token surfaces as authentication expired — run tinycld auth login. Grants are database rows checked per request, so revoking one from Settings → Personal → Connected apps takes effect on the terminal’s next call.

Scopes requested at login. Each package declares its own from its Go server (oauth.RegisterPackage in server/oauth_scopes.go), naming the collections and routes the scope governs and the label the consent screen shows:

Only the scopes for installed packages appear in a given build.

How a package contributes commands

A package adds a command group by declaring a cli block in its manifest:

cli: {
    package: 'cli',                            // directory, relative to the member root
    module: 'tinycld.org/packages/mail/cli',   // Go module path
},

and exposing a single entry point from that Go module:

func Register(root *cobra.Command, c *client.Client)

There is deliberately no command list in the manifest — Cobra owns the command tree and generates --help from it. There is no scope list either: the package’s Go server registers its OAuth scopes with core (oauth.RegisterPackage), and the CLI’s device-flow login requests whatever the installed packages registered.

The generator (pnpm run packages:generate) emits cli/cli_extensions.go with the imports and Register calls, a cli/go.work covering each member’s cli/ directory, and cli/search_slugs.go listing searchable packages. All three are generated and gitignored — see Generated files.

A package whose cli.package directory is absent is skipped silently. The CLI module must not import tinycld.org/core; the few shared structs it needs are mirrored locally, with a comment naming the source.

Because the command tree is compiled, a server without a package has no trace of its commands — there is no runtime gating to configure.

Build and distribution

Built with Go and Cobra. To build locally, run the generator first:

cd tinycld && pnpm run packages:generate
cd cli && go build .

A local build reports its version as dev; releases stamp it via -ldflags "-X main.version=<v>".

Servers cross-compile the binary as a step of the package-build pipeline, with CGO_ENABLED=0 and -trimpath -ldflags "-s -w", for five targets: darwin/arm64, darwin/amd64, linux/amd64, linux/arm64, and windows/amd64. Artifacts land in <appDir>/cli-dist/. The step is best-effort: a target that fails to compile is logged and skipped, and never fails the package install.

There is no package registry, Homebrew tap, or auto-updater. The server distributes its own binary over two public endpoints — GET /api/cli/downloads lists the available platforms, and GET /api/cli/download/{platform} streams one. Both are public because a browser download link cannot carry an authorization header; {platform} is resolved by lookup against a fixed target list, so it cannot be used to traverse the filesystem.