The CLI

The Trokky CLI is a single Go binary. Most of its commands talk to a running instance over the HTTP API; three of them (create, migrate, config) work on files and need no server at all.

brew install trokky/tap/trokky

There is also an install script and Windows archives on the releases page, and go install github.com/Trokky/cli@latest from source.

Choosing an instance

Every command that talks to a server needs a URL and a token. They are resolved in this order, and the first complete answer wins:

1. --url and --token together on the command line.
2. TROKKY_URL and TROKKY_TOKEN in the environment.
3. The configured instance — --instance <name>, else TROKKY_INSTANCE, else the default instance.

Configured instances live in ~/.trokky/config.yaml, written by trokky login and trokky config add.

Flags available on every command:

Flag	Effect
--url	Instance API URL.
--token	API token.
--instance	Use a named configured instance.
-q, --quiet	Suppress informational output.

URLs are normalised: https://cms.example.com and https://cms.example.com/api both resolve to https://cms.example.com/api, because /api is appended when it is missing.

create

Scaffolds a new project.

trokky create my-site --template blog --data filesystem

With no --template and no -y, it prompts for each choice. With a template, it takes that template’s defaults and applies any flags you gave on top. -y alone uses the minimal template.

Flag	Values
-t, --template	minimal, full, api-only
--data	filesystem, postgres
--media	filesystem
--mail	none, resend, console
--auth	basic, oauth, none
--studio	embedded, separate, none
--captcha	none, turnstile, recaptcha
--i18n	none, en, fr, en-fr
--examples	Include example schemas.
-y, --yes	Skip prompts.

The target directory must not exist or must be empty.

login

trokky login https://cms.example.com

The URL is a positional argument, not a flag. This runs the OAuth2 device flow: the CLI prints a short code and a verification URL, tries to open your browser, and polls until you approve in the Studio. On success it stores the access token, the refresh token and the expiry under an instance name.

Flag	Effect
--name	Instance name. Defaults to the URL’s hostname.
--set-default	Make this the default instance. On by default; pass --set-default=false to keep your current default.

The instance must have the OAuth2 server enabled. If it does not, the first request fails — see Users and authentication.

logout

trokky logout            # the default instance
trokky logout staging

Removes the stored credentials for an instance. It is the same operation as trokky config remove. Prompts for confirmation unless you pass --force.

status

trokky status

Prints the resolved instance URL, whether the instance answers its health check and how long that took, then every collection with its document count split into published and draft. It takes no flags of its own.

This is the command to reach for when a token is not working: it tells you which URL and which credentials the CLI actually chose.

backup

trokky backup --output backup.zip

Flag	Effect
--output	Archive path. Required.
--collections	Comma-separated collections to include.
--skip-media	Do not download media files.
--description	Text stored in the archive manifest.

restore

trokky restore --input backup.zip --dry-run

Flag	Effect
--input	Archive path. Required.
--collections	Comma-separated collections to restore.
--with-dependencies	Also restore what the selected collections reference.
--clean	Delete existing content before restoring.
--overwrite	On a failed create, retry as an update at the original id.
--dry-run	Validate and report without writing.

Restore regenerates document ids for everything except singletons. Read Backup and restore before you run it against anything you care about.

migrate

Upgrades a project from the split v0.1.x packages to the consolidated v2 packages. It works on files only — no URL, no token, no running server.

trokky migrate --dry-run
trokky migrate --write

Flag	Effect
--path	Project directory. Defaults to ..
--dry-run	Report changes without writing. This is the default behaviour.
--write	Rewrite files in place.
-y, --yes	Skip the confirmation prompt.
--force	Write even when the git working tree is dirty.

--dry-run and --write are mutually exclusive. Without --force, the command refuses to write into a dirty git tree, so that you can always diff and revert the migration.

It rewrites @trokky/* module specifiers across JS, TS and Astro sources and pins the three v2 packages in every package.json. node_modules, dist, build, .git, .astro and symlinks are left alone.

It also reports what it cannot fix: imports of package internals, Astro’s build-time inlining of import.meta.env.TROKKY_API_URL, and structure entries marked as singletons whose schema does not declare singleton: true. That last one is a data-loss trap — fix those warnings before restoring anything into the migrated site. See Singletons.

generate-types

trokky generate-types -o ./src/types/trokky

Fetches the schemas from the running instance and writes TypeScript interfaces.

-o, --output is a directory, not a file. The command creates it if needed and writes index.ts inside it. The default is ./src/types/trokky.

Because the types come from the instance rather than from your source files, a schema change is only reflected after the server restarts with it. See Generated types.

documents

Aliased to docs. Five subcommands.

documents list

trokky documents list posts --limit 5 --status published
trokky documents list posts --sort _createdAt --order desc
trokky documents list posts --filter '{"featured":true}'

Flag	Default	Effect
--limit	20	Maximum documents returned.
--offset	0	Documents to skip.
--page		1-based page number, used with --limit.
--search		Full-text search query.
--filter		JSON filter object.
--sort		Field to sort by.
--order	asc	asc or desc.
--status		published or draft.
--expand		Expand reference fields.
--format	json	json, table or ids-only.
--count		Print the count only.

Sorting is translated into the server’s prefix notation: --sort _createdAt --order desc is sent as sort=-_createdAt. A field already written directionally — -_createdAt, _createdAt.desc, _createdAt.asc — is passed through untouched and --order is ignored for it.

--status is folded into the filter as _status. If you combine it with --filter, the filter must be a JSON object or the command fails.

documents get

trokky documents get posts post-123 --field title

Takes a collection and an id. --expand expands reference fields; --field extracts one value by dot-path instead of printing the whole document.

documents create

trokky documents create posts article.json
trokky documents create posts --data '{"title":"Hello"}'
cat data.json | trokky documents create posts

The document comes from a file argument, from --data, or from stdin. --status sets published or draft. --validate checks the document against the schema before sending — it verifies required fields and the types of top-level string, number, boolean, array and object fields, and does not look inside nested objects or arrays.

documents update

trokky documents update posts post-123 --data '{"title":"New title"}'

Same input options as create, plus a document id. This is a partial update: fields you do not send are left as they are. Send null to clear one. That behaviour is the server’s, and it is explained under Things that will bite you.

documents delete

trokky documents delete posts post-123 post-456

Takes one or more ids. Prompts for confirmation unless you pass --force.

query

There is no trokky query command. Querying documents from the command line is trokky documents list with --filter, --search and --sort; from application code it is the client SDK, covered in Querying.

export

trokky export article articles.json
trokky export article            # to stdout

Writes one collection to a JSON file, or to stdout when you give no output path. There are no flags. The command’s own help text shows an --all example; that flag does not exist and the example does not work.

export is not a backup: it captures documents from one collection and nothing else — no media, no manifest, no dependency information. Use trokky backup for anything you intend to restore.

import

trokky import article articles.json

Reads a JSON array of documents, or an API response wrapping one, and posts each document into the collection. Both arguments are required.

Two things to know. Documents that fail to import are skipped silently — the command reports how many succeeded, not which ones did not. And the --upsert flag is accepted but has no effect: every document is created, so importing the same file twice produces duplicates.

config

Manages the instances in ~/.trokky/config.yaml.

trokky config add production --url https://cms.example.com/api --token "$TOKEN"
trokky config list
trokky config use production
trokky config remove staging
trokky config path

Subcommand	Notes
add <name>	Flags: --url, --token, --description, --default. Prompts for anything missing; the token prompt does not echo.
remove <name>	--force skips the confirmation.
list (ls)	Every configured instance, with tokens masked.
use <name>	Sets the default instance.
path	Prints the config file path.

config add stores a token you already have. trokky login gets you one through the browser. Use add for API tokens and CI, login for your own machine.

clean

Deletes content from an instance. This is the destructive one.

trokky clean --dry-run
trokky clean --collections posts,pages --confirm

Flag	Effect
--collections	Restrict to these collections.
--media-only	Delete media, leave documents.
--documents-only	Delete documents, leave media.
--dry-run	Report what would be deleted.
--confirm	Required for an actual deletion.

Without --dry-run or --confirm the command refuses to run and tells you so. --media-only and --documents-only cannot be combined. With no --collections, it discovers every collection on the instance and empties all of them.

There is no undo. Take a backup first, and check that the backup restores somewhere else before you rely on it.