Command line tool

Every TinyCld server builds its own copy of the tinycld command line tool, containing exactly the command groups for the packages installed on that server. A server with Drive and Mail offers tinycld drive and tinycld mail; a server without Mail has no mail command at all.

Download and first run

Open Settings → Personal → About in the app and find Command line tools. Download the build for your platform, then make it executable:

chmod +x tinycld

The binaries are unsigned in this version. macOS blocks the first run until you clear the quarantine flag; Windows shows a SmartScreen warning (choose More info → Run anyway).

xattr -d com.apple.quarantine ./tinycld

Log in

tinycld auth login your-server.example.com

The tool prints a short one-time code and opens your browser. Confirm the code matches and approve the device. The login is a scoped, revocable grant — it appears under Settings → Personal → Connected apps, and revoking it there signs that terminal out remotely on its next request.

tinycld auth status shows who you are logged in as and which scopes the grant carries. tinycld auth logout revokes the grant and forgets the credentials.

Working with more than one server

Each server you log into is saved as a context. Log in against a second host to add one:

tinycld context list              # the current context is marked with *
tinycld context use work
tinycld context add lab https://lab.example.internal
tinycld context remove lab        # also deletes its stored credentials

Any command takes --context <name> to run against a different server just once, without switching.

Where your credentials live

Contexts are saved in ~/.config/tinycld/config.toml (mode 0600; set $TINYCLD_CONFIG_DIR to move it, and Windows uses your user config directory instead).

Tokens are not in that file. They go to the operating system’s keychain — macOS Keychain, Windows Credential Manager, or libsecret — under the service name tinycld. If no keychain is available the tool falls back to ~/.config/tinycld/credentials/<context>.json at mode 0600 and warns you that it has done so.

Access tokens refresh automatically. If the refresh token itself has expired or been revoked, commands fail with authentication expired — run tinycld auth login.

Work with your files

tinycld drive ls /Projects -l
tinycld drive tree /Projects --depth 2
tinycld drive put report.pdf /Projects
tinycld drive put ./photos /Albums --recursive
tinycld drive get /Projects/report.pdf .
tinycld drive search "roadmap"

Paths work like shell paths from /. Anywhere a path is accepted you can also pass id:<record-id> to skip path resolution. Uploads go through the same server rules as the app — name de-duplication, quotas, sharing — and downloading a folder produces a zip. mkdir, mv, cp, rm, trash, restore, and usage round out the basics.

Sharing, links, versions, and PDF export are here too:

tinycld drive share /plan.docx --user ada@example.com --role editor
tinycld drive link create /plan.docx --role viewer --expires 2026-12-31T23:59:59Z
tinycld drive versions /plan.docx --snapshot --label "before rewrite"
tinycld drive export /plan.docx report.pdf

share grants access to people who already have an account on the server; link manages public links, including revoking them.

Search and send mail

tinycld mail search "invoice" --from billing --has-attachment
tinycld mail read <thread-id>
tinycld mail send --to "Ada <ada@example.com>" --subject "Report" --body-file - < notes.txt
tinycld mail status

Search flags mirror the app’s advanced search. read prints a whole thread as plain text (--no-mark leaves your unread counts alone), download saves attachments, and status reports unread counts per mailbox.

Replies, drafts, and filing work from the terminal as well:

tinycld mail reply <thread-id> --all --body "Thanks all."
tinycld mail draft --to ada@example.com --subject Later --body wip
tinycld mail draft send <draft-id>
tinycld mail archive <thread-id>...
tinycld mail label add <thread-id> Work

--from picks which of your addresses — including aliases — a message is sent as. Folder moves, labels, stars, and read state change only your own view of a shared mailbox; other members are unaffected.

Track work on boards

tinycld boards list
tinycld boards view "Roadmap"
tinycld boards column show --board Roadmap
tinycld boards card add "Fix the login bug" --board Roadmap --list Triage
tinycld boards card move <card-id> --board Roadmap --list Doing
tinycld boards card edit <card-id> --due 2026-09-01

Boards resolve by id, by key, or by name, so you can use whichever is convenient. Lists are the columns on a board: boards column add, rename, move, category, and wip manage them, where category says whether a column counts as backlog, to-do, in progress, done, or canceled. Removing a list deletes the cards in it. Cards can be linked, copied, reacted to, and tied to GitHub pull requests; boards sprint plans, starts, and completes sprints; and boards export / boards import round-trip a board as CSV or JSON, including a Trello export.

Board sharing and membership are not exposed on the command line — manage those in the app. The whole group appears only once the Boards package is installed.

Keep your address book

tinycld contacts list
tinycld contacts search "ada"
tinycld contacts add --first Ada --last Lovelace --email ada@example.com
tinycld contacts edit <id> --company "Analytical Engines"
tinycld contacts export --out contacts.vcf
tinycld contacts import contacts.vcf

rm moves a contact to the trash rather than deleting it. The round trip back out is tinycld contacts list --trashed to find it and tinycld contacts edit <id> --restore to bring it back; --permanent is the only flag that actually destroys a record. Import matches on the vCard UID, so re-importing the same file updates contacts instead of duplicating them.

Read and edit your calendar

tinycld calendar agenda --days 14
tinycld calendar list
tinycld calendar add --title "Design review" --start "2026-09-01 14:00" --guest ada@example.com
tinycld calendar rsvp <event-id> yes
tinycld calendar export --calendar Team --out team.ics
tinycld calendar import team.ics

Calendar access has two levels: you can read any calendar you are a member of, but only owners and editors can change one. tinycld calendar list prints a ROLE column, which is the only advance warning you get — a write to a calendar you are merely subscribed to fails at the server. rsvp works only if you are actually on the event’s guest list.

Comment on documents and spreadsheets

tinycld text comments /Specs/plan.docx
tinycld text comments /Specs/plan.docx --add "Looks good to me" --quote "the second phase"
tinycld calc comments /Models/budget.xlsx --add "Check this figure" --cell B12 --sheet sheet1
tinycld calc comments /Models/budget.xlsx --resolve <comment-id>

Both groups offer a single comments command that reads a thread, adds to it, and resolves or reopens it. Spreadsheet comments anchor to a cell, given in ordinary A1 notation, plus the sheet’s id; replies inherit their thread’s anchor.

There is no text new or calc new. Documents and workbooks are Drive files, so tinycld drive put, cat, get, and rm already manage them. Their contents are collaborative edit operations rather than plain text, which is why the command line reads and writes comments but not the body.

Scripting and CI

Every command accepts:

Without a terminal the tool never blocks on input and turns off color on its own, so it runs cleanly in cron jobs and CI:

tinycld drive ls /reports --json | jq -r '.[].name'
tinycld mail status --json | jq '.[0].inbox'

Two things to know before you script against it. JSON output is not a transcription of the table. Several commands deliberately return a richer or differently-keyed document than the columns they print — drive tree nests, where the table draws ASCII; boards list keys boards by slug; calendar list carries role and kind as fields; mail read returns the raw message array. Check the actual JSON for a command before depending on a field name.

Warnings go to stderr. tinycld search writes result counts and any partial- or truncated-result warnings to stderr specifically so that stdout stays a single clean JSON document you can pipe into jq.

Going further

tinycld <group> --help lists every command in a group, and tinycld <group> <command> --help gives its full flag list. The CLI reference documents the whole surface, including exit codes and the scopes each group requests. On servers where the packages are installed, the in-app help hub covers each group in more detail.