Every command is a subcommand of gansey. gansey --help and gansey <command> --help list the options, and gansey --version prints the version.
Common options
| Option | Variable | What it does |
|---|
--config <path> | GANSEY_CONFIG | read this gansey.toml instead of ./gansey.toml |
--database-url <url> | DATABASE_URL | the Postgres URL, overriding the configuration |
--config works with every command and goes anywhere on the line. --database-url is taken by every command that uses the database; on a command group it comes before the next subcommand, as in gansey user --database-url <url> list. Most people set DATABASE_URL instead.
serve and migrate
| Command | What it does |
|---|
gansey serve | start the site, the API and the admin |
gansey serve --migrate | apply pending migrations first, then serve |
gansey serve --bind <address> | listen on this address (GANSEY_BIND) |
gansey serve --port <port>, -p <port> | listen on this port (GANSEY_PORT) |
gansey migrate | apply pending migrations and exit |
gansey serve --migrate --port 9000
gansey migrate
Without a database URL, serve still starts and shows the built-in welcome page.
doctor
| Command | What it does |
|---|
gansey doctor | check the database, migrations, users, media and logs folders, backup tools, email and public URL; exit 1 on a failure |
gansey doctor
user
| Command | What it does |
|---|
gansey user create --email <email> | create an account; the first one becomes administrator, later ones editor |
--name <name> | display name; defaults to the part of the email before @ |
--password <password> | the password; asked for when left out |
--role <slug> | administrator, editor, author, viewer or a custom role's slug |
gansey user reset-password --email <email> | set a new password (asked for, or --password) and sign out the account's sessions |
gansey user list | list accounts with their status and roles |
gansey user create --email [email protected] --name "Site owner"
gansey user reset-password --email [email protected]
backup
| Command | What it does |
|---|
gansey backup now | take a backup; --note <text> records why |
gansey backup list | list backups, newest first |
gansey backup restore <name> | take a safety backup, then restore the named one |
gansey backup restore 20261016-030000
self-update
| Command | What it does |
|---|
gansey self-update --check | report the current and latest versions and the licence, and install nothing |
gansey self-update | install the latest release on the channel; restart the service afterwards |
gansey self-update --rollback | put gansey.previous back |
gansey self-update --check
mod
| Command | What it does |
|---|
gansey mod list | list modules in the modules folder with their version, source and status |
gansey mod add <source> | install from a folder, a .tar.gz file, a git repository (https://…/name.git#tag, user@host:path, git+…), a package URL, or a registry package id (blog for the newest version that fits this core, [email protected] for that version); --ref and --path pick a repository's branch, tag or commit and the folder holding the module |
gansey mod remove <id> | remove a module, keeping its tables; --purge drops them too |
gansey mod enable <id> | switch a module on again |
gansey mod disable <id> | switch a module off, keeping its folder and data |
gansey mod new <id> | create a starter module; --name <name> sets its name |
gansey mod pack <folder> | pack a module into <id>-<version>.tar.gz; --out <dir> says where |
gansey mod publish <folder> | pack a module and publish it to the hub |
gansey mod test <folder> | run a module's tests |
mod enable and mod disable need the site's database. A running server picks the change up the next time it reloads the module.
mod publish takes --token (GANSEY_REGISTRY_TOKEN, from the hub's Packages screen), --hub (GANSEY_HUB_URL, else [updates].hub_url), --public-key (GANSEY_RELEASE_PUBLIC_KEY) and --if-newer, which does nothing unless the version is newer than every version the registry has. mod test takes --database (GANSEY_TEST_DATABASE_URL, a scratch database; it refuses one that holds a site), --filter and --core. See Publishing and Testing.
gansey mod add ../modules/blog
gansey mod disable blog
gansey mod remove blog --purge
page, theme and site
| Command | What it does |
|---|
gansey page export <file> | write every page with its latest and published documents to a JSON file, or - for standard output |
gansey page import <file> | create or update pages from an export; --publish publishes the ones that were published |
gansey theme export <file> | write the published theme, its parts and their files to a .ganseykit.tgz; --name names the kit |
gansey theme import <file> | install a kit as drafts; --publish publishes it and makes its parts the defaults |
gansey site export <dir> | write the published site into a folder: pages, theme, parts, blocks, content types, taxonomies, entries, assets and site.toml (with redirects) |
gansey site import <dir> | bring a site folder into the database, skipping anything unchanged; --publish publishes the changes and applies the module switches and redirects |
site commands apply pending migrations before they start.
gansey theme export coastal.ganseykit.tgz --name "Coastal"
gansey site import sites/example --publish
render
| Command | What it does |
|---|
gansey render <file> | render a page document (or - for standard input) to HTML on standard output |
--theme <file> | a theme token document to render with; the defaults otherwise |
--title <title> | the page title; Preview by default |
render needs no database.
gansey render page.json --theme tokens.json > page.html
signing-key
| Command | What it does |
|---|
gansey signing-key new --out <file> | write a new signing key readable only by its owner and print its public half |
gansey signing-key show | print the public half of the configured key |
release
For core's release workflow: publishes a built binary to the hub. The hub hashes and signs the file, and the command checks the signature before it succeeds.
| Option | What it does |
|---|
gansey release publish <binary> | the built gansey executable to upload |
--version <version> | the release version; this build's version by default |
--channel <channel> | stable by default |
--platform <platform> | linux-x86_64, linux-aarch64, macos-x86_64 or macos-aarch64; this machine's by default |
--target <triple> | the Rust target the binary was built for, instead of --platform |
--changelog <text>, --changelog-file <file> | the release notes |
--draft | store the file without publishing the release |
--hub <url> | the hub (GANSEY_HUB_URL, else [updates].hub_url) |
--token <token> | the publish token from the hub's Releases screen (GANSEY_PUBLISH_TOKEN) |
--public-key <hex> | the key the signature must verify against (GANSEY_RELEASE_PUBLIC_KEY); the hub's own otherwise |
gansey release publish target/release/gansey --channel beta --changelog-file CHANGES.md