CLI Commands

The cmd/server binary doubles as a CLI: passing any argument switches it into CLI mode, where commands are dispatched through internal/cli (built on github.com/dracory/base/cli) instead of starting the HTTP server.

go run ./cmd/server <command> [args...]

Available Commands

Command	Description
task <alias> [args...]	Execute a registered background task synchronously by its alias (see Background Tasks)
job [args...]	Execute a one-off job with arguments (dispatched via internal/cmds)
routes list	List all registered HTTP routes
maintenance enable|disable|status	Toggle or inspect maintenance mode (aliases: on/down = enable, off/up = disable)

Maintenance Mode

Maintenance mode is a file-based, CLI-toggleable state that returns 503 Service Unavailable for all requests. The middleware sits first in the global middleware chain so it short-circuits everything when active:

go run ./cmd/server maintenance enable    # turn maintenance mode on
go run ./cmd/server maintenance status    # check current state
go run ./cmd/server maintenance disable   # turn maintenance mode off

The state is persisted to a JSON file (default maintenance_mode_state.json, configurable via APP_MAINTENANCE_FILE_PATH). APP_MAINTENANCE_ENABLED=true can also force maintenance mode via the environment — see the Environment guide.

Adding Commands

Register new commands in internal/cli/cli.go. The dispatcher is generic over app.AppInterface, so handlers receive the fully booted application:

func NewDispatcher() *cli.Dispatcher[app.AppInterface] {
    dispatcher := cli.NewDispatcher[app.AppInterface]()

    _ = dispatcher.RegisterCommand("mycommand", "Describe what it does", func(app app.AppInterface, args []string) error {
        // ...
        return nil
    })

    return dispatcher
}

CLI mode runs after configuration load, migrations, and task registration, so commands have access to all initialized stores and services.