Reference49 min read
The collage CLI
Every command of the collage CLI, from new, add and dev to plugin, ai, completion and man, with its flags and exactly what it runs.
The collage command scaffolds projects and drives the ones you have: running one in development, compiling the binary you deploy, and exporting it as static files.
go install github.com/Elagoht/collage/cmd/collage@latest
It never links your application into itself — it cannot, because your application is your code. dev, build, export, inspect and check run the go tool in the current directory, exactly as you would by hand, and the rest of this page says precisely what each one runs.
Usage
collage <command> [flags]
| Command | What it does |
|---|---|
new | Scaffold a new collage project |
add | Write a page, fragment, action, document, layout, guard, middleware or command into the current project |
dev | Run the current directory's project in development mode |
build | Compile the current directory's project into the binary you deploy |
export | Render the current directory's project to static files |
serve | Serve a static export the way a static host would |
routes | List every URL the current directory's project answers, with the guards each meets |
inspect | Print what the current directory's project is made of, as JSON |
check | Check the current directory's project's templates without rendering them |
plugin | Add a plugin to the project, remove one, or check a plugin repository |
ai | Write or refresh the project's AGENTS.md, the rules for coding agents |
completion | Print a shell completion script for bash, zsh or fish |
man | Print collage's man page, or install it where man finds it |
version | Print the collage CLI version |
help | Show help for a command, or list every command |
collage help <command> prints that command's own usage, and so does collage <command> -h. Flags use Go's flag syntax: -out dist and -out=dist are the same, and --out works too.
A mistyped name ends its error with the closest valid one:
collage: unknown command: "chek" (did you mean "check"?)
That goes for every name the CLI knows the valid set of: a command, a subcommand, an add kind, a flag, a --template, a @bundle, and a plugin — one a bundle names for plugin add, one plugins.go has for plugin del. A name close to none of them gets the error alone, and the exit code is the same either way.
collage new scaffolds it once. While you work on it, add, dev, check, plugin add and del, and inspect all act on the project in the current directory. To ship it, collage build compiles one binary for a server, which listens on HOST and PORT, and -i writes an image file and a service unit beside it. Or collage export renders dist/, which collage serve shows as a static host would before you upload it. collage plugin check is not in the picture: it runs in a plugin's own repository.Exit codes
| Code | Meaning |
|---|---|
0 | Success, including help, collage -h and collage <command> -h |
1 | The command parsed correctly and failed to do its work |
2 | A usage problem: no command, an unknown command, a bad flag, or an unexpected argument |
collage new
collage new <name> [--template minimal|demo] [--with plugins] [--dir path] [--module path] [--force] [--ai]
Scaffolds a new, runnable project named <name>.
| Flag | Default | Meaning |
|---|---|---|
--template name | minimal | The project to scaffold: minimal or demo |
--with plugins | none | Plugins to add once it is scaffolded: bundles such as @prod and plugins such as elagoht/session, separated by commas or in more than one --with |
-dir path | ./<name> | Directory to scaffold into |
-module path | <name> | The module path written into go.mod |
-force | off | Scaffold into a non-empty directory anyway |
--ai | off | Write AGENTS.md, the rules for coding agents, and a CLAUDE.md importing it, as collage ai init does |
collage new myblog # into ./myblog, module "myblog", one page
collage new myblog --template demo # the demos and their tests
collage new myblog -module github.com/me/myblog
collage new . # into the current directory, named after it
collage new myblog -dir . -force # into the current, non-empty directory
collage new myblog --with @blog,@prod # and the plugins of two bundles
collage new myblog --ai # and AGENTS.md for coding agents
--with is read before anything is written: a bundle that does not exist or a plugin name that cannot be read is a usage error, and no directory is made. Once the project is scaffolded, new requires the collage the CLI is, then adds each plugin as collage plugin add would. A plugin that fails is reported and left out; the project and the other plugins stay, and the command exits 1. What each plugin added needs from you — its setup note, template functions and documentation — comes last, together.
The scaffolded main.go reads BASE_URL into Config.BaseURL: the origin a sitemap, a canonical link or a feed puts in front of a path. Empty is fine until a plugin that writes one is added.
Flags take one dash or two, and may come before or after the name. Exactly one name is required; none, or more than one, is a usage error.
<name> is the project's name and, unless --module says otherwise, its module path, so it must be one: letters, digits and - . _ ~, as go mod init takes, in elements separated by /, none empty and none starting or ending with a dot. A path as the argument — . above all — scaffolds there and names the project after that directory; --module is how a directory such as my site gets a module path. With --dir the argument is only a name and cannot be a path. A name or a --module that is not a valid module path is refused with exit code 2 before anything is written.
A target directory that exists and is not empty is refused unless you pass -force — and with -force, files the scaffold writes replace files of the same name, and the command names them: go.mod among them is your module path and dependencies. Scaffolding into the directory you are in leaves cd out of the next steps.
The scaffolded go.mod requires Go 1.26.11, the oldest Go collage builds with.
Every project gets:
go.mod;- a
main.goof about fifty lines:newApp, which builds the configuration and the static mount from thecollage.Envit is given, and amainthat hands it tocollage.Main, which keeps the CLI contract described below and dispatches plugin commands; embed.goandembed_dev.go, which declarefiles: templates, static files andplugins-config.json, embedded, or the project directory in a development build (see below);- a
plugins.goand aplugins-config.json, empty, and a.env.example; - a
routes.goregistering every route; - a layout that names the site with
WithTitleand declares no slots (so a page's own title replaces the site's); - a home page whose markup is inline in its Go file, handed the project's name with
collage.Value— static without sayingStatic(), because nothing in it fetches; static/, a.gitignoreand a README.
Copy .env.example to .env, which collage dev, go run . and the built binary read; with --template demo the next steps the command prints say so.
--template demo adds a page of live demos — an action answering JSON, a form posting to its own page, a fragment with its own URL, a JSON document — a not-found page, tests for each written with collagetest, and a favicon.
The layout is by area, the layout of a real application:
pages/<area>/<name>.go a page: its layouts, content, path, actions
fragments/layouts/master.go Master(), the layout every page wraps itself in
fragments/pages/<area>/<name>.go each page's content, mirroring pages/
actions/<area>/<name>.go an action and its handler, one per file
documents/<name>.go routes that are not HTML
data/<domain>/ state, by domain
templates/layouts/ the layouts' HTML
pages/ and fragments/pages/ mirror each other by area, and every package in them is called pages or fragments, so a page file imports its content as fragments "<module>/fragments/pages/<area>" and routes.go imports each area's pages under an alias, demopages. Pages and fragments keep their markup inline, as a collage.InlineHTML const beside their data handler, and only layouts keep theirs in templates/layouts/. Editing a page's markup is a Go change, which collage dev rebuilds for. In the layout's <head>, {{hoist "head"}} comes after the site's stylesheet, so a stylesheet a fragment hoists wins over the site's at equal specificity. An action a page attaches with WithActionFor shares the page's name and has no path of its own. routes.go registers everything with one app.Register call.
The minimal project, the default, is the least a project can be: the layout around one page, <h1>Hello from {{.Name}}</h1> — the project's name, handed to the template with collage.Value — and a stylesheet that sets the background and text colour, dark mode included. Nothing else — no tests, and no not-found page: collage answers an unknown address with its own plain 404 until you register one.
When it is done it prints the next steps:
cd myblog
go mod tidy
collage dev
collage add
collage add <kind> <[area/]name> [flags]
Writes a page, a fragment, an action or a document in the scaffold's layout, and registers it in routes.go — and a layout, a guard, a middleware or a command:
collage add page blog/post # pages/blog/post.go + fragments/pages/blog/post.go
collage add page blog/post --file # its template in templates/pages/blog/post.html
collage add fragment blog/sidebar # fragments/blog/sidebar.go, for a slot
collage add fragment layouts/partials/siteFooter --file
# fragments/layouts/partials/siteFooter.go
# + templates/layouts/partials/siteFooter.html
collage add action blog/comment # actions/blog/comment.go, the action and its handler
collage add action blog/ping --path /api/ping
collage add document feed --path /feed.xml --type application/xml
collage add action blog/like --page blog/post # attached to pages/blog/post.go
collage add layout panel # fragments/layouts/panel.go, nested
collage add guard admin # guards/admin.go, the guard function alone
collage add layout panel --guard admin # a layout that carries it
collage add page admin/users --layout panel
collage add page login --guard guest # WithGuard on the page's content
collage add middleware loadUser # middleware/loadUser.go + app.Use in routes.go
collage add command seed # commands/seed.go + app.RegisterCommand
| Flag | Default | Meaning |
|---|---|---|
--file | off | Keep the template in a file under the template root, not inline |
--path pattern | /<area>/<name> | The URL; an action without one answers at the page it is attached to |
--name name | the last segment | The page's, action's, document's or command's name |
--locale code | Locale.Default, or en | The locale its path is in |
--type type | text/plain; charset=utf-8 | A document's content type |
--layout name | none | A page's layout: the one add layout <name> wrote, inside the site's |
--guard name | none | .WithGuard(guards.<Name>), the guard add guard <name> wrote: on a page's content, a layout or an action |
--page target | none | An action's page, [area/]name: attaches the action to it |
--dir path | . | The project |
- A page is
pages/<area>/<name>.go, wrapped inlayouts.Master()— or the first layout infragments/layoutsthat takes no arguments — with its content infragments/pages/<area>/<name>.go: a template, a view struct, and a typedcollage.Loadhandler that declares the page's title. The handler is made by<name>Data() collage.Data, which the content's function calls, so a service the handler needs is a parameter added to both — see Data handlers. - An action is
actions/<area>/<name>.go, one per file as a page is: its builder, and its handler under it —<name>Handler(), a factory like a fragment's data handler, so a service it needs is a parameter away. Its package isactions, imported as<area>actions(blogactions) the way an area's pages are<area>pages; with no area it isactions/<name>.go. Actions already inactions/<area>.gofiles oractions/funcs/are left untouched, and new ones go into folders beside them. With--pathit answers at a URL of its own and is registered; without one it answers at the page it is attached to, and the command prints the.WithActionFor(...)to add. --page <[area/]name>attaches a new action to that page instead of printing how: it adds.WithActionFor(blogactions.Like())before theBuild()that ends the page'sNewPagechain, importing the action's package. A page file with more than one chain is left alone, and the line to add is printed. It cannot go with--path.- A document is
documents/<name>.go. - A layout is
fragments/layouts/<name>.go, a layout that nests inside the site's own around a page's content,<div class="<name>">{{slot "content"}}</div>— inline, or in a template file with--file.--layout <name>wraps a new page in it, and--guard <name>gives the layout that guard. A layoutadd layoutwrote is marked//collage:nested, and one that carries a guard counts as nested too: neither is ever taken for the site's layout a new page goes into. - A guard is
guards/<name>.go, the guard function alone: aGuardFuncthat refuses everyone with403until you write its check — returnnil, nilto let a request through, or a redirect.--guard <name>puts it where it is asked, adding.WithGuard(guards.Admin)and nothing else; the guard must exist, or the command is refused with theadd guardto run first. Onadd pageit goes on the page's content fragment — a page's builder has no guard of its own — so the page's renders, its attached actions and its fragment paths meet it. Onadd layoutit goes on the layout, and every page wrapped in it meets the guard first. An action with its own--pathhas no page;add action ... --guard admingives it the guard itself. - A middleware is
middleware/<name>.go, afunc(http.Handler) http.Handlerthat passes every request on, registered withapp.Useafter the middleware already there — the first registered is the outermost. It runs before routing and guards run after it, so a guard reads what it puts in the request's context: load the signed-in user there, decide in the guard. - A command is
commands/<name>.go, acollage.Commandregistered withapp.RegisterCommand:go run . <name>, or the built binary followed by it, runs it instead of the server.--namegives it a name that is no Go name,user-add; a name anothercollage.Commandin the project has is refused, and so is one that is not a single shell word, asRegisterCommandrefuses it. A middleware or a command that needs a service takes it as an argument you add. Both go into the register function as statements of their own,if err := app.Use(...); err != nil { return err }, which needs one that takes the*collage.Appand returns anerror; otherwise the line to add is printed. - A fragment is a page's content without the page, for a slot of a page or a layout; the command prints the
.WithSlotFragment(...)that binds it. It goes where its path says,fragments/<area>/<name>.go, with its template at<area>/<name>under the template root. Its package is the one already in that directory, or one named after it:fragments/layouts/partialsispartials. A fragment that belongs beside a page's content iscollage add fragment pages/blog/related.
The last segment is a Go name, kept as written: blog/storyDetail, layouts/partials/siteFooter. What the command writes is named after it — the file, the default URL and the name, so blog/storyDetail is the page "storyDetail" at /blog/storyDetail — unless --name gives another, and its function is that name with the first letter capitalised, StoryDetail(). A dashed name is refused, as it is no Go name. The directories before it are only a path and may have dashes, user-settings/profile; their package and import alias drop them, usersettings. An area whose package name would be a Go keyword (type), main, init or a name Go predeclares (string, error, len) is refused, whatever its case (Type too): the first three cannot be a package another file imports, and the last would shadow the built-in in every file that imports it. The locale of its path is Locale.Default as main.go writes it, en when it is not a literal there, or --locale; a template file goes under Template.Root with its Extension, read the same way. The command says which locale it used.
It registers into the list routes.go already keeps: an app.Register(...) call, where the new item goes after the last one of its kind, or a []*collage.Page{...} literal ranged over with RegisterPage — and the same for Document and Action. It edits the file in place, so its comments stay where they were, and imports the area's package under the same kind of alias the scaffold uses. With no such list it changes nothing there and prints the line to add. Constructors take no arguments: a page that needs a service gets it added by hand.
Nothing is overwritten. Everything is worked out before anything is written, and a file that exists, a page, action or document name the project already declares, or an identifier already in the package a file goes into stops the command with nothing written.
collage dev
collage dev
Builds the project in the current directory, runs it with COLLAGE_DEV=1 set, and rebuilds and restarts it whenever its Go code or plugins-config.json changes. It takes no flags and no arguments. Press Ctrl-C to stop; the program receives the interrupt too and shuts down the way it would in production. A SIGTERM, or the SIGHUP a closed terminal sends, stops it the same way: the program is shut down and the temporary build directory removed.
The browser talks to collage dev, not to the program: collage dev listens on HOST and PORT as your program would read them (localhost:6060 by default), and passes each request on to the program, which it starts with HOST and PORT set to a loopback address of its own. That is how it can show errors in the browser when there is no program to answer.
collage dev answers only a request whose Host names this machine — localhost or a name under it, an IP address, a reserved name such as example.com or *.test — or the HOST it was started with, or a name in COLLAGE_DEV_HOST, and refuses anything else with a 403.
A page on another site can make its own name resolve to 127.0.0.1 (DNS rebinding) and would then be same-origin with collage dev: it could read your pages, the development error pages with their stacks, and the program's output. The Host it sends is its own name, which it cannot change.
To reach collage dev under another name, start it with HOST set to it, or list the name in COLLAGE_DEV_HOST, a comma-separated list such as app,mybox.lan for a docker-compose service and a LAN name. collage dev reads it from the shell or the environment file, applies it to its proxy, and starts the program with the list plus its own HOST, since the program listens on loopback but sees the browser's Host; the program applies the same rule in development mode.
collage dev also logs a Warn when its own proxy is bound anywhere but loopback, since the development pages are then reachable from other machines. See Deployment.
What the program prints still reaches the terminal, as the program printed it — with one change: its own address is replaced by collage dev's, so its collage: listening line names the address to open.
On a colour terminal the program is started with FORCE_COLOR=1, which the default logger honours, so its lines keep their time, coloured markers and dimmed attributes although its output reaches collage dev through a pipe; collage dev's own lines take the same shape. NO_COLOR turns both off.
16:10:23 • collage dev: serving http://localhost:6060
16:10:24 • collage: listening addr=localhost:6060
16:10:29 • collage dev: change detected, rebuilding
16:10:29 ✗ collage dev: build failed; waiting for a change
The scaffolded main.go turns on development mode when COLLAGE_DEV=1 is set, and listens on the HOST and PORT it is given: collage.Main puts both in the Env it hands newApp. Development mode reads templates and static files from disk on every request, so editing those needs no rebuild and none happens — the page in your browser reloads itself instead. Content your program reads from disk itself, such as Markdown, reloads the page too once its directory is named in Config.DevWatch. See Templates for what else development mode changes.
Development builds embed nothing
collage dev builds with go build -tags collage_dev, and the scaffold keeps its //go:embed line in embed.go, which starts with //go:build !collage_dev. Beside it, embed_dev.go (//go:build collage_dev) declares the same variable. Development mode reads templates/ and static/ from disk anyway, so a development build has nothing to embed, and collage build, collage export and a plain go build pass no tag and embed them.
The two files declare one filesystem, files. In embed.go it is //go:embed all:templates all:static plugins-config.json; in embed_dev.go it is the project directory itself, os.DirFS("."), so a plugin given files — a card template, a favicon source, Markdown posts — reads the copy you are editing rather than an empty filesystem.
The reason is the Go build cache. A package that embeds files carries them in its compiled form, and a change anywhere in your project recompiles main, so every build that embeds them stores another copy of templates/ and static/ there — one per save, kept for five days. A 30 MB static/ grows the cache by about 30 MB per save; a few hundred saves are gigabytes.
A project whose main package embeds files in a development build — //go:embed lines in a file without the !collage_dev constraint, such as main.go — is told so when collage dev starts, with the file named:
16:10:23 ! collage dev: main.go embeds files into every development build, and each build stores another copy of them in the Go build cache; move the //go:embed lines into a file constrained with //go:build !collage_dev (see collage help dev) patterns=all:static all:templates
To fix it, move the //go:embed variables out of main.go (and "embed" out of its imports) into two files of their own. The ones a new project gets are:
// embed.go
//go:build !collage_dev
package main
import "embed"
//go:embed all:templates all:static plugins-config.json
var files embed.FS
// embed_dev.go
//go:build collage_dev
package main
import (
"io/fs"
"os"
)
var files fs.FS = os.DirFS(".")
go clean -cache reclaims what is already in the cache. Your editor's gopls, which builds without the tag, reports embed_dev.go as excluded by build constraints when you open it; that is expected.
What triggers a rebuild
| Watched | Not watched |
|---|---|
.go files anywhere in the project | _test.go files |
go.mod and go.sum at the project root | templates, static files and DevWatch directories (reloaded without a rebuild) |
plugins-config.json at the project root | hidden directories (.git, .cache, …) |
| the environment file below | bin, dist, node_modules, testdata, vendor |
The skipped directories are what keeps the loop from feeding itself: nothing the running program writes — its cache, an export — can trigger a rebuild. The program reads plugins-config.json once, when it starts, so a setting edited there restarts it through the same rebuild as a change to its code.
How a rebuild goes:
- It polls every 300 ms, comparing modification times and sizes. No file-system notification library, and the same behaviour on every platform.
- A burst of writes is one rebuild. After a change it waits until the files have been quiet for one interval, so a formatter rewriting several files costs one build.
- The new build is made first.
go buildwrites a binary to a temporary directory outside the project; only once it compiles is the old process interrupted — it drains its requests as on Ctrl-C, and is killed only if it has not exited within 10 seconds — and the new one started. - A change that does not compile stops the old process all the same. A build left serving no longer matches the code, and with the terminal out of sight nothing says so; the browser gets the compiler's error instead, as below.
- A program that exits by itself — a panic at startup, a page whose template is missing — is not restarted in a loop. The next change starts it again.
Errors in the browser
A program that is not running is a page, not a refused connection:
- When the program exits — a template not found at registration, a panic at startup — or a build fails, every page is a 503 showing what the program or the compiler printed. A page already open reloads onto it, and reloads again once a change brings the program back.
- A request made while the program starts waits for it, rather than failing because the program is not listening yet.
- A program that never listens where it was told — a
main.gothat ignoresHOSTandPORT— is named on the page after 10 seconds, with the address it was given.
A render that fails once the program is running is the program's own development error page, which leads with the cause — see Errors.
Environment files
collage dev adds the variables of .env.development in the current directory to the program's environment, or of .env when there is no .env.development. One file, never both: .env.development replaces .env rather than being merged over it.
# .env.development
PORT=6060
HOST=localhost
export COLLAGE_CSRF_KEY="0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0"
- The format is
KEY=valuelines, blank lines and lines starting with#. Anexportprefix is allowed, and so is a pair of matching single or double quotes around a value, which are removed with nothing inside interpreted. - An unquoted value ends at a
#that follows whitespace, soPORT=6060 # devis6060. - Keys are letters, digits and underscores, not starting with a digit.
- A malformed line stops the program from starting:
collage devreports it with the file and the line (.env.development:3) and starts or restarts nothing until it is fixed — a program already running keeps running on the values it was started with. It keeps watching, so saving the corrected file carries on. A skipped line would be a setting you wrote and the program never saw. - A variable already set in the shell wins over the file, so
PORT=4000 collage devstill works. COLLAGE_DEV=1is always set, whatever the file says, and so are theHOSTandPORTthe program is to listen on. The file'sHOSTandPORTare wherecollage devitself listens, read once when it starts.COLLAGE_DEV_HOSTis read from the file or the shell too, and the program is given it withcollage dev's ownHOSTadded.BASE_URL, when neither the shell nor the file sets it, iscollage dev's own address,http://localhost:6060. A plugin that writes absolute URLs — a sitemap, a canonical link — refuses to start without an origin, and in development that is the right one. Deployed, set it yourself.- No file is not an error. When a file is read, its name is printed on stderr.
- The file is read again on every restart, and it is watched, so editing it restarts the program with the new values.
A program whose main calls collage.Main, as a scaffolded one does, reads them too, with the same rules: go run ., collage export and the built binary load .env from the working directory — .env.development first under COLLAGE_DEV=1 — before newApp runs, so os.Getenv("BASE_URL") sees it with no source .env. Outside development the file read is named on stderr. On a server that sets its variables itself, the variables win and a missing file is no error; a malformed line stops the program with the file and the line. A main of your own that does not call collage.Main reads no file.
collage build
collage build [-o path] [-os name] [-arch name] [-i]
Compiles the current directory's project into the binary you deploy. It runs:
CGO_ENABLED=0 GOOS=<os> GOARCH=<arch> go build -trimpath -ldflags="-s -w" -o bin/<name> .
| Flag | Default | Meaning |
|---|---|---|
-o path | bin/<name> | Where to write the binary |
-os name | this machine's | Target operating system (GOOS) |
-arch name | this machine's | Target architecture (GOARCH) |
-i | off | Ask which extra files to write beside the binary |
<name> is the last element of the module path in go.mod; a directory with no go.mod, or one that declares no module, is an error. For -os windows, .exe is appended to the path when it is not already there. Positional arguments are a usage error.
Why those settings:
- CGO off, because collage and the standard library need no C, and a static binary can go into an image with nothing else in it.
-trimpath, so the binary does not carry the paths of the machine that built it.-s -wdrops the debug tables, which is most of the size.- This machine by default, so the binary runs where it was built. A server is often something else — a binary built on a Mac does not run in a Linux container — so name it there:
collage build -os linux -arch amd64. bin/, notdist/:dist/is wherecollage exportwrites, andexport -cleanempties it.
When it finishes it prints the binary's path, platform, size and build time.
Extra files with -i
With -i it asks two questions before building, reading answers from standard input — y or yes means yes, anything else no:
- Write a Dockerfile? A two-stage image: a
golangbuild stage pinned to the major and minor version of the Go that built the CLI, and agcr.io/distroless/static-debian12stage holding only the binary, withHOST=0.0.0.0,PORT=8080, port 8080 exposed and a commented-outCOLLAGE_CSRF_KEY. - Write a systemd unit? A
<name>.servicerunning/usr/local/bin/<name>from/srv/<name>withHOST=127.0.0.1,PORT=8080,Restart=on-failureandTimeoutStopSec=30, to adjust before installing.
Both are written beside the binary — bin/Dockerfile, bin/<name>.service — because they are generated, and the project root is for what a person wrote. The report prints the one command that placement costs:
docker build -f bin/Dockerfile .
An existing file is never overwritten. If one is already there the question is not asked. These are files a project edits, and a build command that replaced one with a default would quietly undo somebody's work.
Without -i, only the binary is written. See Deployment.
collage export
collage export [-out dir] [-clean]
Renders the current directory's project to static files — HTML for every page that can be one, plus every mounted asset — for a static host. It runs:
go run . -collage-build -out <dir> # plus -clean when you passed it
| Flag | Default | Meaning |
|---|---|---|
-out dir | dist | Directory the project renders into |
-clean | off | Remove the directory's existing contents before building — only a directory an export made |
The program's output — the build report — is streamed straight through, not reformatted. Positional arguments are a usage error.
-clean (BuildOptions.Clean) empties only a directory an export made: an export leaves a .collage-export marker in a directory it creates, or finds empty, and -clean deletes nothing in a directory without one. It refuses the project's own directory — the working directory, the module root or the repository root — and any directory above it, so -out .. -clean and -out static -clean both stop with ErrDangerousOutDir before anything is deleted or written. A dist/ exported before it carried the marker needs it once:
touch dist/.collage-export
Two outputs whose paths differ only in case — /About and /about — are one file on macOS and Windows, so the export treats them as a collision on every platform, ErrOutputPathCollision, as it does two outputs at the same path, and builds nothing.
A page that declares no strategy is exported when nothing it renders has a data handler; one with a handler is exported when it says Static() or Incremental(ttl). A page whose path has a {param} is exported once per value its WithStaticParams lists, and skipped without one. What gets exported, what is skipped and why, and the safety checks on the output directory are in Static export. For a site with forms or per-request pages, collage build is the one you want.
collage serve
collage serve [-dir dir] [-host name] [-port n]
Serves a static export the way a static host would, so what you see is what you will get after deploying it. It serves files; it does not run your project.
| Flag | Default | Meaning |
|---|---|---|
-dir dir | dist | Directory to serve |
-host name | localhost | Interface to listen on |
-port n | 4000 | Port to listen on |
The port is 4000 rather than 6060 so it can run beside collage dev — which is exactly when you compare the two.
It behaves like a static host rather than a file server:
- A path with no extension is answered with
<path>/index.html, which is the shape an export writes. - Directories are never listed.
- A path that resolves to nothing is answered with the export's own
404.htmland a 404 status, or a plain 404 when there is none. - Only
GETandHEADare answered; anything else is a 405. - A dotfile —
.env,.git/config— is never served. A file whose extension names no type is typed from its content as a mount types it, never into HTML or XML, and every file carriesnosniff. - Every response is sent with
Cache-Control: no-store, so re-exporting and reloading shows the new output rather than the old.
A directory that does not exist, or holds no files, is an error that tells you to run collage export first. A path that exists but is not a directory is an error too, saying just that.
collage routes
collage routes
Lists every URL the project answers through collage, a row per method and path, sorted by path:
METHOD PATH KIND NAME NOTES
GET / page home static
GET /admin/users page users dynamic, guard adminGuard
POST /admin/users action rename on page users, guard adminGuard
POST /api/fire action fire own URL, own guard
POST /api/ping action ping own URL, no guard
GET /static/* mount 12 files
Not listed: handlers mounted with app.Handle, and plugins' own endpoints.
A page says how it is cached and which guards it meets; an action says whether it answers on a page, and so meets the page's guards, or at a URL of its own, and whether it has a guard of its own; a page's fragment URLs are listed with the guards they meet too. A LOCALE column appears when the site has more than one locale. It reads what collage inspect prints, so the project is built and newApp runs. What is not registered through collage — app.Handle, a plugin's own endpoints such as /healthz — is not in the list. It takes no flags.
collage inspect
collage inspect
Prints what the current directory's project is made of, as JSON: every page with its patterns, parameters, layouts (outermost first) and guards, every fragment with its template and slots — an inline fragment with "inline": true and no template path — the documents, the actions, the template functions, the plugins, the locales, and the files the mounts serve. It takes no flags; positional arguments are a usage error. It builds the project as collage dev does and runs the program with COLLAGE_DEV=1:
go build -tags collage_dev -o <temporary file> .
COLLAGE_DEV=1 <temporary file> collage-inspect
Nothing is embedded, so the program reads templates/ and static/ from disk, and the build goes to a file of its own: go run stores the linked program in the Go build cache, and without the tag the compiled main package holds every file the scaffold embeds, so each run after a change to main would store another copy of them there, kept for days. collage routes and collage check run the project the same way. The temporary file is removed when the command ends, and when it is interrupted — Ctrl-C, SIGTERM or SIGHUP — too.
They also set COLLAGE_CLI_COMMAND to the word they ask with. While it is set, App.ListenAndServe refuses to serve and returns why, so a main.go that never hands its arguments to DispatchCommands fails at once instead of leaving the command waiting on a server forever.
collage-inspect is a command DispatchCommands answers itself rather than handing it to a plugin: it prints the application's description as indented JSON. That JSON is the contract; the Go types behind it (App.Inspect, collage.Inspection, collage.InspectCommand) are not part of the public API.
The name is prefixed so that no plugin's command is taken. The scaffolded main.go hands the word after its flags to DispatchCommands (see Plugin commands), so a scaffolded project needs nothing more. A program that does not dispatch its arguments that way has nothing to answer with.
It is what an editor's completion reads: the Collage Snippets & Highlighter extension for VS Code (Editor support) offers page names in {{pageURL "…"}}, slots in {{slot "…"}} and files in {{asset "…"}} from it.
Each fragment also carries the Go type its template sees as ., and the root carries types, a table of the types those reach. An editor can then complete {{. and check a field name the way registration does — see How templates are checked:
"fragments": [
{"name": "post-body", "template": "pages/post.html", "handler": true, "dataType": "*blog.Post"},
{"name": "layout", "template": "layouts/master.html", "dataType": "nil"},
{"name": "legacy", "template": "pages/legacy.html", "handler": true, "dataType": null, "typeCheck": false}
],
"types": {
"blog.Post": {
"kind": "struct",
"fields": [
{"name": "Base", "type": "blog.Base", "embedded": true},
{"name": "ID", "type": "int"},
{"name": "Title", "type": "string"},
{"name": "Author", "type": "*blog.User"},
{"name": "Comments", "type": "blog.Comments"},
{"name": "Related", "type": "blog.Tags"}
],
"methods": [{"name": "URL", "args": 0, "returns": "string"}]
},
"blog.Base": {"kind": "struct", "fields": [{"name": "ID", "type": "int"}]},
"blog.Comments": {"kind": "slice", "elem": "blog.Comment"},
"blog.Tags": {"kind": "map", "key": "string", "elem": "[]blog.Post"},
"blog.User": {"kind": "struct", "fields": [{"name": "Name", "type": "string"}]}
}
dataTypeis always written: the Go type,"nil"for a fragment with no data or withcollage.Effect, andnullwhen the type is an interface and so unknown until the page renders — a handler declared to returnany.typeCheck: falseappears only on a fragment builtWithoutTypeCheck().typesholds every named type reachable from some fragment's data type — through fields, element and key types, and method results — keyed by its Go name, with its exported fields (promoted ones included) and the exported methods of it and its pointer that return something.- An exported embedded field is a field too — a template reaches it as
{{.Base}}— and carries"embedded": true; the fields it promotes are listed beside it as usual. - A named pointer, slice, array, map or chan carries
elem, the type it holds, and a map alsokey. - A type is listed once and named everywhere else, so a recursive type ends. An unnamed struct is listed under its Go spelling; other unnamed composites are written inline in a type string (
[]blog.Comment). - Standard library types such as
time.Timeandtemplate.HTMLare named, not described. typesis left out when no fragment has a known data type.- A key two different types share (
models.Userfrom two packages namedmodels) is written as{"kind": "struct", "ambiguous": true}with no fields or methods, and an editor treats it as unknown.
- An exported embedded field is a field too — a template reaches it as
The output's version is 1.
collage check
collage check [-json]
Checks every template's links without rendering anything. A link built by name — {{pageURL "post" "slug" .Slug}}, {{pageURLIn "en" "about"}}, {{actionURL "logout"}}, {{fragmentURL "home" "clock"}}, {{localeURL "en"}} — fails when the template renders, and only on the page that reaches it. check finds them all at once:
$ collage check
error [unknown-route] inline template of fragment "hello":4:16: {{pageURL "featurs"}}: collage: no page or document by that name: "featurs"; did you mean "features"?
| Rule | What it means |
|---|---|
unknown-route | No page, document, action or fragment path by that name; the closest registered name is suggested |
route-params | The parameters do not fill the route's pattern — one missing, one it has no placeholder for, or not in name and value pairs |
unreachable-locale | A locale no URL can carry: not Locale.Default, nor in Locale.Supported |
no-path-in-locale | The route has no path in the locale pageURLIn or fragmentURLIn names |
It checks with the framework's own URL builders, so what it reports is exactly what a render would fail on. Only names written as string literals are checked: a name from a field, {{pageURL .Name}}, is known only when the template renders, and a parameter whose name is not a literal leaves the parameters unchecked. A link with no locale of its own passes when its route can be built in some locale, since a render falls back to the default one.
It exits 1 when it finds anything, so it can stand in CI before collage build; -json prints the findings as an array of {level, rule, message} for an editor. It runs the program as collage inspect does:
go build -tags collage_dev -o <temporary file> .
COLLAGE_DEV=1 <temporary file> collage-check
which collage.DispatchCommands answers by starting the application and calling App.Check — so a program that opens a database on start opens it here too. A test can call the same function:
if findings := app.Check(); len(findings) > 0 {
t.Errorf("broken links: %v", findings)
}
collage plugin
Adds plugins to the project, takes them out, or checks a plugin repository:
collage plugin add <plugin>... [-dir dir]
collage plugin del <plugin>... [-dir dir]
collage plugin check [-release] [-run] [dir]
collage plugin add elagoht/consent # github.com/elagoht/collage-consent
collage plugin add elagoht/sitemap@v0.3.1 # a version go get accepts
collage plugin add gitlab.com/kisi/plugin # a module path, used as written
collage plugin del elagoht/consent
collage plugin add elagoht/session elagoht/flash # several, in order
collage plugin add @prod # a bundle
collage plugin del @live elagoht/session
collage plugin check -release -run # in a plugin's own repository
owner/name means github.com/<owner>/collage-<name>; a path whose first segment has a dot is a module path and is used as written. add and del work on the project in the current directory, or the one -dir names: it must hold go.mod and a package main.
add fetches the module with go get. Without @version it asks for @upgrade: the latest release for a module go.mod does not have yet, and never a move down for one it has. It then checks that the module is a plugin; the contract is on the plugin authors' page:
- a
collage.jsonat the module root whosenameisowner/name, the one you typed when you gave a short name; - the plugin's package at the module root, not
package main; - a
Newthat can be called with nothing configured: no parameters, a variadic one, or one whose zero value can be written, an exported struct of the package's own aspkg.Options{}, ornilfor a pointer, interface, slice, map or func; - a release tag, not a pseudo-version.
It adds the plugins the manifest requires first, then writes the import and the call into plugins.go, before the first entry whose manifest has a greater order, and an empty section to plugins-config.json. It ends with go mod tidy:
$ collage plugin add elagoht/consent
added elagoht/consent v0.2.0
plugins.go consent.New(consent.Options{})
plugins-config.json "elagoht/consent": {}
elagoht/consent
The banner needs its categories and wording: set `"categories"` (at least one) and `"text"` (the default locale's wording, labelling every category; other locales under `"locales"`) in this plugin's section of `plugins-config.json`. Without categories the application does not start.
Docs: https://github.com/Elagoht/collage-consent
It then prints what the plugin still needs from you, from its manifest: its setup note, the template functions it adds, each with the first sentence of its description, and its documentation's address. With several plugins — a bundle, new --with — these come together at the end, under "What each plugin needs from you". An empty section means the defaults, and a setting the plugin requires is reported by the plugin when the application starts.
- The import is named after the package. When that name is already an import of
plugins.go, or a name declared anywhere in the package, it becomes<owner><Name>, and then gets a number. - A plugin
plugins.goalready has is not added twice. Only its version moves, and the command says so. - An existing section is kept. Both files are edited in place, so your arguments, comments, order and formatting stay.
- Nothing is left half-done. Any failure, Ctrl-C included, puts
go.mod,go.sum,plugins.goandplugins-config.jsonback as they were. A file that was absent is removed again.
A project without a plugins.go gets the file from its first add, and the command prints the Plugins: plugins(), line to give collage.New, once. A scaffolded project already has both.
del finds the plugin among plugins.go's entries, by the name in their manifests or by the module path, in any case. It removes its entries, its import and its section, prints the section when it held settings, and runs go mod tidy. It refuses:
- while another plugin's manifest
requiresit; - when another entry's
collage.jsoncannot be read (the module cannot be fetched, or the file is malformed), since it cannot then tell whether that plugin requires this one; the message names the module and the reason; - when it was given a module path and the plugin's own
collage.jsoncannot be read, since the name of its section is then unknown.
Another entry's collage.json is read for its name, requires and order only, so a key from a newer manifest schema stops nothing. An entry wired by hand that is not a plugin module's root package (a package of your own module, or a subpackage of a dependency), or a module with no collage.json, requires nothing and stops nothing. A module the module cache lacks, as after a fresh clone, is fetched to read its manifest. Like add, del puts every file back when a step fails.
Several at once
add and del take several plugins, and work through them in the order given. Each is a step of its own: one that fails is reported and put back, and the ones before and after it stay. The command then exits 1. A name that cannot be read stops the command before anything changes, as does one plugin given with two versions; a plugin given twice is done once.
With more than one, a summary follows, and add prints the plugins' setup notes together at the end rather than after each:
$ collage plugin add elagoht/feed elagoht/nope elagoht/toc
added elagoht/feed v0.3.0
...
collage: plugin add: elagoht/nope: ...
added: elagoht/feed, elagoht/toc
failed: elagoht/nope
To finish setting up:
elagoht/feed
Feeds are Go values: give them to `feed.New(...)` in `plugins.go`, ...
del takes the order off your hands: a plugin another one on the list requires is removed after that one, so del elagoht/live elagoht/websocket works.
Bundles
A bundle is a set of plugins under one name, written with @: collage plugin add @prod, collage new site --with @blog. Its plugins are added in the order below, and each goes to the place in plugins.go its manifest asks for. del @name removes those of a bundle's plugins the project has and passes over the rest. collage help plugin lists them too.
| Bundle | For | Plugins |
|---|---|---|
@prod | what a site in production wants | health, secure, compress, minimizer, accesslog, ratelimit |
@site | a public site's search and share basics | robots, sitemap, meta, jsonld, favicon |
@blog | @site, and a feed, contents and share cards | the plugins of @site, feed, toc, ogimage |
@forms | forms, and state kept in cookies | session, flash, validate, honeypot |
@live | fragments the server keeps current | live, websocket |
@ops | metrics and error reports | prometheus, errortrack |
Every plugin is elagoht/<name>. Some need a setting before the application starts: sitemap and meta the site's origin (BASE_URL in a scaffolded project), favicon a source image, ogimage a filesystem given in plugins.go, errortrack a DSN outside development. Their setup notes say what to do, and the application refuses to start, naming the setting, until it is done.
check checks a plugin repository (dir, default .) against the contract add enforces. The check itself reads only the repository:
-releasealso wants a release tag atHEAD, which needs git;-runbuilds a throwaway program in the repository'scollage-plugin-check/directory and runs it, which fetches what the module cache lacks. The directory has one name, so the Go build cache keeps one copy of the program; one already there — another check running, or one interrupted — is refused and left alone. It callsNewexactly asaddwould write it, as acollage.Plugin, and checks thatName()is the manifest'sname. It fails on a build error, a panic inNewor a different name. It does not configure or start the plugin, so a setting an empty section lacks is not its concern.go.mod,go.sumandgo.work.sumare put back and the program is removed afterwards.
These are commands of the collage binary. A plugin's own subcommands are another thing: see Plugin commands.
collage ai
collage ai init [--dir path]
collage new mysite --ai # the same, while scaffolding
Writes the rules a coding agent needs to work in a collage project — opencode, Codex, Cursor, Claude Code — into the project's AGENTS.md. They say where each kind of file goes (and that collage add puts it there), that a change to a layout reaches every page under it, how guards reach an action, how CSS is hoisted, and which plugin to add instead of writing one. They are short on purpose: an agent that has never seen collage, often a small model, reads them first and follows them over its own habits.
collage writes only its own section, between two markers:
<!-- collage:begin v1.0.0 — written by `collage ai init`; … -->
…
<!-- collage:end -->
## Project rules
- Run it again after upgrading collage to refresh that section. Everything outside the markers — the project's own rules — is kept byte for byte.
- An
AGENTS.mdwithout the markers gets the section above its text. - Markers that are not one begin line followed by one end line are refused, and nothing is written: which text is collage's would be a guess, and a wrong guess deletes your rules.
- A
CLAUDE.mdholding@AGENTS.mdis written too when the project has none, so Claude Code reads the same rules. An existing one is never changed; the command says so when it does not importAGENTS.md.
It prints what it did with each file — created, updated, or current when the section is already what it would write:
AGENTS.md: created
CLAUDE.md: created
collage completion
collage completion bash|zsh|fish
Prints a script that completes commands, flags and their values when TAB is pressed: add's kinds, plugin add's bundles and the plugins they name, --template's templates, --with's list item by item, and paths for --dir, -o and -out. Load it from the shell's startup file:
eval "$(collage completion bash)" # ~/.bashrc (works with macOS's bash 3.2)
source <(collage completion zsh) # ~/.zshrc, after compinit
collage completion fish | source # ~/.config/fish/config.fish
The script asks the collage on PATH what to complete, through a hidden collage __complete command, so it stays right after an upgrade with nothing to reload. Each command's flags are declared once and read by both the command and completion, so a new flag completes the day it exists. Commands a project's plugins add run through the project's own binary, and are not completed.
collage man
collage man # print collage(1)
collage man --install # write it where man finds it
Prints collage(1), the man page, made from every command's own help text. --install writes it to ../share/man/man1/collage.1 beside the directory on PATH that holds collage — $(go env GOPATH)/share/man for go install, ~/.local/share/man for a link in ~/.local/bin. man searches there for every directory on PATH, so man collage works with nothing else set up. The command says so when the binary is not on PATH, or when MANPATH is set without the empty entry that keeps those directories in.
collage version
collage version
Prints collage version <version>. The version is read from the binary's build information, so go install ...@v1.0.0 reports 1.0.0, and a binary built in a git checkout reports a pseudo-version — 1.0.1-0.<timestamp>-<commit> for a commit after the v1.0.0 tag. Only a binary with no version information at all — built outside a repository, or with -buildvcs=false — reports devel.
collage help
collage help # every command
collage help export # one command's usage
With no argument it lists every command and exits 0. With a command name it prints that command's usage; an unknown name prints collage: unknown command: "nope", with the closest command after it when one is close, and exits 2.
Example: from a new project to a first deploy
The commands above, in the order a site meets them: a project called myblog, written on a laptop and deployed to a server of another platform. Times, sizes, hashes and cache directories in the output differ on your machine.
1. Scaffold it.
collage new myblog
cd myblog
go mod tidy
new writes the minimal project and prints the next steps:
Scaffolded "myblog" in myblog
Next steps:
cd myblog
go mod tidy
collage dev
The scaffolded go.mod names only the module and the Go version, 1.26.11; go mod tidy adds collage to it.
2. Run it.
collage dev
01:13:17 • collage dev: serving http://localhost:6060
01:13:18 • collage: dev mode is rendering templates from disk, not the embedded copy root=templates
01:13:18 • collage: dev mode, using an in-memory cache instead of the configured disk cache
01:13:18 • collage: listening addr=localhost:6060
http://localhost:6060 shows Hello from myblog. Leave it running: the next step adds Go files, and it rebuilds when they appear.
3. Add a page, and check the links. In a second terminal:
collage add page about
wrote fragments/pages/about.go
wrote pages/about.go
edited routes.go
locale en, from the default; main.go sets no Locale.Default literal, --locale changes it
page "about" at /about
collage dev rebuilds, and /about answers. Then:
collage check
01:14:05 • collage: dev mode, using an in-memory cache instead of the configured disk cache
collage: check: nothing found
The first line is the program's own, since check starts it, in development mode. The second is the verdict, and the exit code is 0; in CI, this is the step before collage build.
4. Build for the server. The laptop is not the server, so name the server's platform, and ask for the two extra files with -i:
collage build -i -os linux -arch amd64
Building myblog for linux/amd64.
Write a Dockerfile? [y/N]: y
Write a systemd unit? [y/N]: y
✓ bin/myblog
linux/amd64 · 10.3 MB
wrote bin/Dockerfile docker build -f bin/Dockerfile .
wrote bin/myblog.service
10.3 MB · linux/amd64 · 6.7s
The scaffold's .gitignore ignores bin/myblog by name and not the two files beside it: those are yours to edit and commit. Run the command again and both questions are skipped, since the files are there.
5. Put it on the server. The two files are two ways to run it, and only one of them uses bin/myblog:
- The service unit runs the binary you built. Copy
bin/myblogto/usr/local/bin/myblogon the server, adjust the unit'sUserandWorkingDirectory— the file cannot know them — and install it where its first comment says. It listens on127.0.0.1:8080, for a reverse proxy in front. - The image file builds its own binary: its first stage compiles the project from source with the same flags, and its second stage holds the result. Build it from the project root, as the report says. It listens on
0.0.0.0:8080.
The 8080 is those files' own setting, written as PORT=8080. The binary run with no HOST or PORT listens on localhost:6060, the scaffold's default; see Deployment. Both files also carry a commented-out COLLAGE_CSRF_KEY: set it to at least 32 random bytes, or a key is generated per process and every form submitted before a restart is refused after it.
Add plugins before -i. The image file copies plugins-config.json only when the project has one as the file is written, and -i never rewrites the file; a plugin added afterwards means adding that COPY line by hand.
Or export it. For a host that serves files, collage export -clean renders dist/ instead, and its report leaves the new page out:
✓ 3 files written
dist/index.html
dist/static/app.css
dist/static/app.f106e88ebb47f51d.css
▲ 1 skipped
about page uses the dynamic render strategy, which cannot be built statically
3 written · 1 skipped · 0 failed · 1.5ms
collage add gave about a collage.Load handler and no strategy, so it is dynamic. Add .Static() to its builder in pages/about.go and the next export writes dist/about/index.html too. collage serve then shows dist/ on localhost:4000, as a static host would serve it.
The contract with main.go
dev, export and inspect depend on three things your main.go does, and collage.Main, which the scaffolded one calls, does all three. The third, handing the words after its flags to collage.DispatchCommands, is also what runs your plugins' commands:
| Command | Runs | Your main.go must |
|---|---|---|
collage dev | go build -tags collage_dev, then the binary, with COLLAGE_DEV=1, the HOST and PORT to listen on, and COLLAGE_DEV_HOST | turn on development mode when COLLAGE_DEV is 1, and listen on HOST and PORT |
collage export | go run . -collage-build -out <dir> [-clean] | parse -collage-build, -out and -clean, and on -collage-build render to <dir> instead of serving |
collage inspect | go build -tags collage_dev, then the binary with collage-inspect and COLLAGE_DEV=1; routes and check too | turn on development mode when COLLAGE_DEV is 1, and pass the words after its flags to collage.DispatchCommands |
collage build needs nothing from main.go: compiling is something go build does without being told anything.
The scaffolded main.go leaves all of it to collage.Main:
func main() {
collage.Main(newApp)
}
func newApp(env collage.Env) (*collage.App, error) {
pluginConfig, err := env.PluginConfig(files)
if err != nil {
return nil, err
}
app, err := collage.New(&collage.Config{
DevMode: env.Dev,
BaseURL: os.Getenv("BASE_URL"),
Server: collage.ServerConfig{Host: env.Host, Port: env.Port},
Template: collage.TemplateConfig{
FS: files,
Root: "templates",
Extension: ".html",
},
Cache: collage.CacheConfig{
Enabled: true,
Type: "disk",
Dir: env.CacheDir,
DefaultTTL: 5 * time.Minute,
},
PluginConfig: pluginConfig,
Plugins: plugins(),
Security: collage.SecurityConfig{
CSRFKey: []byte(os.Getenv("COLLAGE_CSRF_KEY")),
},
})
if err != nil {
return nil, err
}
if err := register(app); err != nil {
return nil, err
}
return app, app.Mount("/static/", env.Static(files, "static"))
}
collage.Main loads the environment file, parses -collage-build, -out, -clean and -port, and calls newApp with a collage.Env:
| Field | Value |
|---|---|
Dev | COLLAGE_DEV=1, which collage dev sets |
Host | HOST, or localhost |
Port | -port, PORT, or 6060 |
CacheDir | .cache; a test passes a directory of its own |
env.PluginConfig(files) reads plugins-config.json from the working directory when it is there, so a deployment can change a setting without a rebuild, and otherwise the copy the binary embeds, so a binary deployed without the file keeps its settings. env.Static(files, "static") serves the static directory from disk in development and embedded otherwise. Then collage.Main dispatches a plugin's command, renders to -out on -collage-build, or serves, and shuts the application down after a build or a command.
A test calls newApp(collage.Env{CacheDir: t.TempDir()}). A main written without collage.Main keeps the contract this way (trimmed to the part that matters):
func main() {
buildFlag := flag.Bool("collage-build", false, "render the app to static files instead of serving it")
outFlag := flag.String("out", "dist", "output directory for -collage-build")
cleanFlag := flag.Bool("clean", false, "remove -out's existing contents before building")
port := 6060 // -port, then PORT, then 6060
if p, err := strconv.Atoi(os.Getenv("PORT")); err == nil {
port = p
}
portFlag := flag.Int("port", port, "port to listen on (env PORT)")
flag.Parse()
host := os.Getenv("HOST")
if host == "" {
host = "localhost"
}
app, err := newApp(collage.Env{
Dev: os.Getenv("COLLAGE_DEV") == "1",
Host: host,
Port: *portFlag,
CacheDir: ".cache",
})
if err != nil {
log.Fatal(err)
}
// A word after the flags is a plugin's command: go run . <command>
if args := flag.Args(); len(args) > 0 {
code, err := collage.DispatchCommands(context.Background(), app, args)
if err != nil {
fmt.Fprintln(os.Stderr, err)
}
if err := shutdown(app); err != nil {
fmt.Fprintf(os.Stderr, "shutdown: %v\n", err)
code = max(code, 1)
}
os.Exit(code)
}
if *buildFlag {
buildErr := staticBuild(app, *outFlag, *cleanFlag)
if err := shutdown(app); err != nil {
log.Printf("shutdown: %v", err)
buildErr = errors.Join(buildErr, err)
}
if buildErr != nil {
log.Fatalf("static build: %v", buildErr)
}
return
}
if err := app.ListenAndServe(); err != nil {
log.Fatal(err)
}
}
// shutdown runs every plugin's Shutdown once a build or a command is done.
// Neither serves, so nothing else would. Only after a successful start: a start
// that failed has already shut down the plugins it started.
func shutdown(app *collage.App) error {
if app.Start() != nil {
return nil
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
return app.Shutdown(ctx)
}
// staticBuild renders the application into outDir and prints the report.
func staticBuild(app *collage.App, outDir string, clean bool) error {
report, err := collage.Build(context.Background(), app, collage.BuildOptions{
OutDir: outDir,
Clean: clean,
})
collage.PrintBuildReport(os.Stdout, report, err)
return err
}
A build and a command serve nothing, so ListenAndServe never shuts the application down for them. collage.Main calls app.Shutdown itself once either is done, and a main of your own does it as above, so every plugin's Shutdown runs: what a plugin holds is flushed, and work handed to a queue plugin such as elagoht/jobs is at least logged when it is dropped.
If you write main without collage.Main, keep all of it working, or collage dev, collage export, collage inspect and your plugins' commands stop doing anything useful in your project.
Plugin commands
Adding and removing plugins is collage plugin. This section is about a plugin's own subcommands. A plugin can contribute one through Host.RegisterCommand. The collage CLI does not run it. The CLI never loads your application, so a command that only exists once your plugins have started is out of its reach, and collage <plugin-command> is an unknown command.
Your own program dispatches them, with collage.DispatchCommands. collage.Main, which the scaffolded main.go calls, already does. A main of your own does it this way (the block above): after the flags are parsed and the application is built, a word left over is a command:
if args := flag.Args(); len(args) > 0 {
code, err := collage.DispatchCommands(context.Background(), app, args)
if err != nil {
fmt.Fprintln(os.Stderr, err)
}
if err := shutdown(app); err != nil { // see above
fmt.Fprintf(os.Stderr, "shutdown: %v\n", err)
code = max(code, 1)
}
os.Exit(code) // runs no defers, so the shutdown comes first
}
DispatchCommands starts the application — running every plugin's Init, which is what registers their commands — and runs the command named by the first argument. So a plugin's command runs as your program's subcommand, after any flags:
go run . pages
./bin/myblog -port 4000 pages
The exit code follows the CLI's:
| Code | When |
|---|---|
0 | success |
1 | a startup failure, a command that ran and failed, or a command with no Run |
2 | a nil app, no arguments, or a word no plugin registered (ErrUnknownCommand) |
An unclaimed word is a usage error rather than a server started by accident. One word no plugin registers is answered all the same: collage-inspect, which collage inspect runs. A program that would rather serve when no command matches can check errors.Is(err, collage.ErrUnknownCommand) and carry on instead of exiting. app.Commands() lists what the plugins registered, if you want to print your own usage.
RegisterCommand refuses a name it could never run: one that is not a single shell word (collage.ErrInvalidCommandName), a collage- name, which DispatchCommands answers itself, and, for a plugin's command, one of the collage binary's own names (both collage.ErrDuplicateCommand). Once the application has started it is collage.ErrAppStarted: a command registered then would never run. See Writing a plugin.
Dispatching starts the application, which closes registration, and a later ListenAndServe reuses that start. DispatchCommands does not shut the application down, since a program may go on to serve it: once a command has run, call app.Shutdown yourself, as above, so that every plugin's Shutdown runs; collage.Main does. Writing such a command is covered in Writing a plugin.