Commands

Commands are app entry points for developer, operator, and application workflows.

They run through the App lifecycle, use injected dependencies, and are exposed through forj and the App binary.

Running Commands

Use the command name directly for the default app:

forj route:list
forj reports:reconcile
forj worker
forj scheduler

Use the app name first to select an additional app:

forj admin route:list
forj admin reports:reconcile
forj admin worker
forj admin scheduler

Inside a GoForj Project, native GoForj commands take precedence. If no native command matches, GoForj delegates to the active App. Use forj run <command> when you want to force default App command execution explicitly, and use ./bin/<app> <command> when running a built binary.

The command runs inside the App, not as an ad hoc shell script around it.

Create a Command

Create a command for the default App:

forj make:command reports:reconcile

Prefix the generator when an additional app owns the command:

forj admin make:command reports:reconcile

internal/reports/reconcile_cmd.go    created
app/wire/inject_cmd_app.go           provider added
app/commands.go                      command exposed

For an additional app, the generated command stays under internal/...; the registration files live under the owning app's app/<name>/....

In existing-file excerpts, highlighted lines are injected by this command.

The generated command starts with its CLI signature and the shared App logger:

internal/reports/reconcile_cmd.go

// ReconcileCmd handles the reports:reconcile app command.
type ReconcileCmd struct {
	logger *logger.AppLogger
}

// Signature keeps command metadata with the implementation so generated wiring stays package-local.
func (*ReconcileCmd) Signature() string {
	return `name:"reports:reconcile" help:"Reconcile command"`
}

// NewReconcileCmd receives shared app services through Wire for this command.
func NewReconcileCmd(logger *logger.AppLogger) *ReconcileCmd {
	return &ReconcileCmd{logger: logger}
}

// Run is the entrypoint Kong calls after parsing reports:reconcile.
func (c *ReconcileCmd) Run(ctx context.Context) error {
	_ = ctx
	c.logger.Info().Msg("ReconcileCmd executed!")
	return nil
}

The generator adds the constructor to the App command provider set:

app/wire/inject_cmd_app.go

// appCommandSet provides app-owned command providers.
var appCommandSet = wire.NewSet(
	reports.NewReconcileCmd,
)

It also exposes the command through the collection Kong parses:

app/commands.go

// Commands wires application-specific commands into the CLI.
type Commands struct {
	ReportsReconcileCmd reports.ReconcileCmd `cmd:""`
}

// NewCommands constructs the application command collection.
func NewCommands(
	reportsReconcileCmd *reports.ReconcileCmd,
) *Commands {
	return &Commands{
		ReportsReconcileCmd: *reportsReconcileCmd,
	}
}

Build and run the generated command before replacing its starter behavior:

forj build
go test ./...
forj reports:reconcile

Expected output includes:

ReconcileCmd executed!

For an additional app, use forj admin build and forj admin reports:reconcile.

Replace the starter body with the application workflow and add its service to the constructor. Wire will satisfy the new dependency after its provider is in the App service set.

The make:command reference covers output overrides, removal, and the exact registration changes. Keep command code focused on flags, input translation, output, and calling application services.

Command Responsibilities

Commands are a good fit for:

• explicit operator tasks
• one-off maintenance actions
• local development utilities
• data reconciliation
• bootstrap tasks
• running runtime boundaries such as workers or schedulers

Commands should not become unstructured backdoors around application services.

Context and Cancellation

Generated commands can receive the CLI lifecycle context directly. Pass it to the service instead of replacing it with context.Background():

internal/reports/reconcile_cmd.go

// Run delegates reconciliation to the service while preserving CLI cancellation.
func (c *ReconcileCmd) Run(ctx context.Context) error {
	return c.service.Reconcile(ctx)
}

Long-running services should check cancellation between units of work and pass the same context into repositories and clients:

internal/reports/service.go

// Reconcile processes pending reports until the work completes or the caller cancels.
func (s *Service) Reconcile(ctx context.Context) error {
	reportIDs, err := s.reports.PendingIDs(ctx)
	if err != nil {
		return err
	}

	for _, reportID := range reportIDs {
		if err := ctx.Err(); err != nil {
			return err
		}
		if err := s.reconcileOne(ctx, reportID); err != nil {
			return err
		}
	}
	return nil
}

The CLI context is cancelled when the command lifecycle stops, including interrupt-driven shutdown. Runtime commands such as HTTP, queue workers, and the scheduler receive the same lifecycle-managed cancellation behavior.

Use context.Background() only at a boundary that genuinely has no caller context. A generated command's Run(ctx context.Context) method already has one.

Next Steps

• make:command Reference shows generation, placement, and wiring.
• Naming Conventions defines stable command names.
• Application Services explains where command behavior should delegate.
• Wiring Recipes shows the command wiring flow.
• App Lifecycle explains command startup and shutdown.
• Testing explains how command tests fit the broader test strategy.
• Console provides standalone messages, ANSI-aware layout, tables, prompts, loaders, and progress for command output.