Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.
Commands and the app binary

Commands and the app binary

Your app builds to one binary that is both the server and its maintenance tool. app.Execute() reads the first argument and runs that command: run by default, or serve, migrate, route:list and commands of your own. Code generation lives elsewhere, in the anetos developer tool, because it writes source code rather than running the app.

    flowchart LR
    A["./blog args"] --> D{"first argument"}
    D -->|"none, or only flags"| R["run"]
    D -->|"help, -h, cmd -h"| H["print usage<br/>(no boot)"]
    D -->|unknown| E["exit 2"]
    D -->|a command| K{"ManagesApp?"}
    R --> K
    K -->|"yes: run, serve"| AR["app.Run<br/>boot, run components,<br/>shut down"]
    K -->|no| B["app.Boot → Run(ctx) → app.Close"]
  

Where commands come from

There is no global registry. Commands are registered on the App, by the code that wires the part they belong to:

CommandRegistered by
run [--only=type,…] (the default), help, version, doctor, aboutEvery app
serve, route:listweb.NewServer
openapiopenapi.Register (Describe an API with OpenAPI)
typestypescript.Register (Generate TypeScript types for the frontend)
migrate, migrate:rollback, migrate:reset, migrate:fresh, migrate:status, db:seed, db:schema, search:reindexmigrate.New (Migrations, Search)
cache:clearcache.New (Cache)
queue:work, queue:failed, queue:retry, queue:forget, queue:flush, queue:clearqueue.New (Queues)
pubsub:publishpubsub.New (Pub/sub listeners)
schedule:list, schedule:run, schedule:test, schedule:workschedule.New (Scheduling)
rbac:roles, rbac:user, rbac:assign, rbac:unassignrbac.New (Roles and permissions)
Your ownapp.Command or app.AddCommand

So a binary only offers commands for what it actually set up: without migrate.New, ./blog migrate is an unknown command. Registering one name twice is an error.

// illustrative
app.Command("reports:send", "Email the weekly report", func(ctx context.Context, args *cmd.Args) error {
	return reports.Send(ctx, args.Stdout)
})

How a command boots and closes the app

There are two kinds of commands:

  • Commands that manage the app (ManagesApp: true): run and serve. They call app.Run, which boots the app, runs the selected components until a signal, and shuts down in stages.
  • All others run between app.Boot and app.Close. Their context comes from app.Context, so it carries what the app provides, such as the database. app.Close runs the shutdown hooks afterwards, even if the command panics, so connections are closed.

help, -h, <command> -h and unknown commands are answered before anything boots. Because db.Connect pings the database at boot, not when it is called, ./blog help works with no database. Every command that boots, route:list included, needs the database reachable.

An app runs one command: afterwards it is stopped and can’t boot again, so tests call app.ExecuteArgs on a new app each time.

Signals and exit codes

The command’s context is canceled on the first SIGINT or SIGTERM; a second signal ends the program at once.

Exit statusWhen
0Success; help; run or serve stopped by a signal (that is how they end)
1The command returned an error, including a command other than run/serve cut short by a signal
2Usage errors: an unknown command, a bad flag, an error from cmd.Usagef

Scripts and orchestrators can rely on these codes: a failed ./blog migrate in a deploy step exits 1.

Process types: one binary, several shapes

run --only=web runs the components of the web process type plus those without one; serve is the same as run --only=web. Your own components get process types with anetos.ProcessTypes. A process type no component has and no package declared is an error, so a typo in --only fails at startup. The same binary can run the web tier on some machines and background work on others. See the runtime supervisor.

The developer tool is a different program

anetos (module anetos.dev/anetos/cli) runs on your machine, not on servers. It writes your project’s source files and runs the development loop:

anetos commandDoes
newCreates a project
devRegenerates, rebuilds and restarts the app on every change
make:handler, make:model, make:migration, make:middlewareWrite new source files; never overwrite
generateWrites typed model columns (Code generation)
key:generateSets a new APP_KEY in .env when it has none (--show prints one; --force replaces a set key, keeping the old one in APP_PREVIOUS_KEYS)

The split follows what each needs. The app binary carries your compiled code, which is what migrating and listing routes need. The tool reads and writes your source, which only exists on your machine. Added with go get -tool, it is pinned in go.mod and adds nothing to the app binary. anetos dev runs the app binary with run, or with the arguments you give after --.

Coming from another framework? What Django’s manage.py, Laravel’s artisan or Rails’ bin/rails do is split in two here. ./blog migrate is built into your app’s binary and runs in production; go tool anetos make:model writes source, so it runs only on your machine. Custom commands are functions registered on the app, not classes.

Related