Gala CLI

Create a publication, write posts, preview them, and publish - from your terminal.

Requirements

• Git
• Node.js 20 or newer
• A GitHub account

Nothing to install. Every command runs through npx.

Start a publication

Sign in once. The CLI binds the verified Gala and GitHub identities together, names the account profile after the GitHub username, and makes it active.

npx --yes @rathnasgala/cli@latest auth add

Use auth list to inspect every pair, auth use <github-login> to change the active account, and auth remove <github-login> to forget one. Tokens from different profiles are never combined.

Create it in the current empty folder:

mkdir field-notes && cd field-notes
npx --yes @rathnasgala/cli@latest init

Or name a new destination directly:

npx --yes @rathnasgala/cli@latest init field-notes

The destination must be empty. An initialized Git repository with no commits and no files is also accepted and its .git directory is preserved. To reserve a custom domain during setup, add --domain blog.example.com; Gala still requires GitHub ownership verification and healthy DNS before activating it.

It uses the selected profile, creates the repository, registers the publication, and leaves a working checkout in the folder. GitHub starts the first deployment in the background. The command links to that deployment rather than presenting the public address as live before GitHub has finished.

On the first run, it opens GitHub's Gala App installation page. Choose the account Gala may use, finish the installation, and return to the terminal; the same command resumes automatically.

If the Gala GitHub App has not been given access to the new repository, it says so and links to the one page that grants it - GitHub has no way for an app to grant itself access, so that click is unavoidable. Everything else is automatic.

Write

Every command continues to run through npx; init does not install a global gala executable. To see every command, run:

npx --yes @rathnasgala/cli@latest --help

npx --yes @rathnasgala/cli@latest new "The places we return to"

This creates a local Markdown draft; it does not publish anything. It also tells you the address the post will use after a successful publication. Without --language, Gala uses the publication's site.defaultLanguage. Write below the second --- line.

Create one new article in several languages at once:

npx --yes @rathnasgala/cli@latest new "A multilingual idea" --languages en,ta,fr

This creates index.en.md, index.ta.md, and index.fr.md in one post folder. They share one article ID and URL name, so the publication presents them as language choices on one article and keeps their interactions and analytics together. The working title is copied into every file; localize each title and body before publishing. If one requested language already exists, Gala leaves that file unchanged and creates only the missing variants.

Add a language to a post that already exists by using the post folder's URL name:

npx --yes @rathnasgala/cli@latest new "மொழிபெயர்க்கப்பட்ட தலைப்பு" --language ta --translation-of a-durable-idea

The new file reuses the existing article ID. If the target does not exist, Gala lists the available post URL names instead of silently creating an unrelated article. Existing language files are never overwritten. Run npx --yes @rathnasgala/cli@latest new --help to see these forms in the terminal.

npx --yes @rathnasgala/cli@latest preview

Builds the publication and serves it locally, using the exact framework version the repository is pinned to - so what you see is what gets published. The first run installs that tooling, which takes a moment. Stop it with Ctrl-C.

Appearance themes

List the official releases Gala has reviewed and see which ones support this publication's pinned framework:

npx --yes @rathnasgala/cli@latest theme list

Stage the newest compatible release of a theme in the checkout, inspect the complete site locally, and publish only after approving it:

npx --yes @rathnasgala/cli@latest theme use awesome
npx --yes @rathnasgala/cli@latest preview
npx --yes @rathnasgala/cli@latest publish

theme use verifies the exact registered repository commit, CSS hash, and byte count before it updates site.config.yml and the local CSS artifact. It does not commit or send anything to GitHub. Use --version 1.0.0 to choose an exact active release. Run theme status to compare the local choice with GitHub, or theme use built-in to stage a return to Gala's built-in appearance. If a release needs a newer framework, the command names the required version and the exact upgrade command instead of hiding the theme.

npx --yes @rathnasgala/cli@latest publish

Checks your content, records it, and sends it to GitHub. GitHub builds and deploys from there; the site updates a minute or two later.

Prism configurations

Prism keeps one canonical work while letting you explicitly approve alternate reading depths and intents. The CLI uses Gala's public lifecycle API; it never writes approval artifacts itself.

npx --yes @rathnasgala/cli@latest prism status
npx --yes @rathnasgala/cli@latest prism create my-post --language en --depth brief --intent orientation
npx --yes @rathnasgala/cli@latest prism list my-post --language en

Use prism edit, submit, approve, reject, and revoke to advance a configuration. Approval, rejection, revocation, and reducing the publication mode require terminal confirmation or --yes. Configuration links default to nofollow; change the publication or one work with prism link-policy when ordinary followed links are intentional. Commands that change repository artifacts stay attached through Gala's materialization and GitHub Pages publication states, then print the live publication address or a concrete terminal failure. Proposal generation likewise waits until its revision is ready for review or generation fails.

Custom domain

Reserve a domain after setup. The command configures everything GitHub already permits and stops only when ownership, DNS, certificate issuance, or Pages propagation requires time or user action:

npx --yes @rathnasgala/cli@latest domain set blog.example.com
npx --yes @rathnasgala/cli@latest domain check

domain check resumes the same workflow and advances every automatic step. domain status reports where an interrupted change is waiting, domain cancel restores the committed address, and domain remove returns the publication to its GitHub Pages address. After removal, delete the old DNS records. While a custom-domain change is pending, the page may become reachable before Gala can authorize that origin. Reader sign-in, comments, reactions, and view tracking activate only after domain check reports that the custom domain is live with enforced HTTPS.

When something is wrong

npx --yes @rathnasgala/cli@latest doctor

Inspect a verified managed-theme release without changing anything unless you confirm it:

npx --yes @rathnasgala/cli@latest upgrade

Reports on your sign-ins, the publication folder, the publishing workflow, and anything you have written but not sent. Each check either passes, names what is wrong and how to fix it, or says it could not be determined - never one of those disguised as another.

Commands

Run any command with --help.

| Command | What it does | Options | | --- | --- | --- | | init | Create a publication in the current or named empty directory | --name, --domain, --account | | domain | Inspect or change the custom domain | --root, --account | | new | Start a post or add translations | --language, --languages, --translation-of, --root, --today | | preview | Build and serve the publication locally | --root, --today | | publish | Check, record and send your work to GitHub | --root, --today, --account, --skip-checks | | prism | Manage author-approved reading configurations | --root, --account, --language, --depth, --intent, --modality, --file, --reason, --yes | | theme | List, stage, preview or restore an official appearance theme | --root, --account, --version | | upgrade | Inspect and apply a verified managed-theme update | --root, --channel, --yes | | doctor | Check a publication and say what is wrong | --root, --account | | auth | Add, list, select or remove GitHub-named account profiles | --api-base-url |

init shows both identities and uses the active account automatically. Registration stores that profile binding inside the checkout's private .git metadata. Later authenticated commands use the binding even if another profile becomes active. --account remains available for an explicit CI or unbound-checkout selection, but it can never override a different bound owner.

Every command prompts for what it needs when run in a terminal, and every prompt has an option that supplies it instead. With no terminal attached - in CI - nothing is ever prompted for: a value that cannot be worked out is an error naming the option, so an automated run fails immediately rather than waiting for an answer that will not come.

Access

The CLI signs in as the Gala GitHub App. It reaches only the repositories you have given that App, and never asks for the broad repo scope, which would have meant read and write access to every repository you can see.

Credentials are stored outside the publication, in your operating system's application-config directory, with private file permissions. Your GitHub sign-in expires after eight hours and the CLI asks you to sign in again rather than quietly using a credential the server will refuse.

Git operations use that same sign-in, not whatever credential your machine happens to have configured - so publishing works on a machine where those differ, or where none is configured.

Troubleshooting

GitHub authentication expired

Sign in again:

npx --yes @rathnasgala/cli@latest auth add

Gala cannot reach the repository

The Gala GitHub App is installed but has not been given this repository. The command prints a link to the installation that needs it; add the one repository and continue. Nothing else needs granting.

A post is not appearing

Run doctor. The most common cause is work written but never sent, which it reports along with the command to fix it.

Something failed and the message was not enough

GALA_DEBUG=1 npx --yes @rathnasgala/cli@latest publish

Prints the full stack. Without it, failures are one line you can act on.

Package and source

Published as @rathnasgala/cli. Source at rathnasgala/cli.