summercms/docs/console/introduction.md

title, description, section, order

title	description	section	order
Console introduction	The two command-line programs of SummerCMS, the summer developer tool and the application binary, and how summer delegates runtime commands.	console	10

Console introduction

WinterCMS has one console entry point, php artisan. SummerCMS has two programs, because the developer tooling and the running application are separate binaries:

Program	Where it comes from	What it does
summer	Installed once, by the curl -fsSL https://summercms.io/new | bash -s -- <name> one-liner or from a framework checkout with go install ./cmd/summer.	Creates, builds and watches applications, scaffolds plugins and their parts, records API parity fixtures and builds these docs.
The application binary, for example ./bin/acme	Written by summer build into the application's bin/ directory.	Runs the application: the HTTP server, migrations, workers, the scheduler, admin accounts and every command its plugins add.

The application binary is what you deploy, so everything that must run in production, such as migrations and workers, is a command of the binary rather than of summer.

Run with no arguments, the binary prints its usage and every command it has, the framework's and those its plugins add; --help prints the same:

./bin/acme
./bin/acme --help

Usage:
  acme [command]

Available Commands:
  admin:create         Create an activated backend administrator
  admin:reset-password Reset a backend administrator password and revoke existing tokens
  admin:token:create   Create a personal API token for a backend administrator
  admin:token:list     List personal API tokens for a backend administrator (or all)
  admin:token:revoke   Revoke a personal API token by id
  admin:token:scopes   List available personal API token scopes
  deferred:purge       Delete expired deferred bindings with their pending uploads and created records
  greeter:hello        Print the configured application name
  help                 Help about any command
  key:generate         Print a fresh 32-byte base64 app.key
  migrate              Run plugin migrations in dependency order
  migrate:rollback     Roll back the last migration of a plugin
  migrate:status       Show per-plugin migration history
  queue:clear          Clear all queued jobs, by deleting all pending jobs.
  queue:work           Run background job workers in the foreground
  route:list           List registered HTTP routes
  schedule:run         Run the scheduler in the foreground (or once for system cron)
  serve                Serve the application HTTP API

Flags:
  -h, --help   help for acme

Use "acme [command] --help" for more information about a command.

Getting help

Both programs list their commands with --help, and every command accepts --help for its arguments and flags:

summer --help
summer make:model --help
./bin/acme --help
./bin/acme migrate:rollback --help

A command that summer delegates to the application binary, such as summer serve, answers --help with the binary's own help, so run it inside an application directory. Asking the help command of summer about a delegated command instead prints a short description and its common flags without running the binary.

Commands that summer delegates

During development you often work from the application directory with summer alone. These summer commands find the application's summer.yaml, build bin/<binary> when it does not exist yet, and run the same command of the binary with the same arguments:

summer command	Runs
summer migrate	./bin/acme migrate
summer migrate:rollback	./bin/acme migrate:rollback
summer migrate:status	./bin/acme migrate:status
summer serve	./bin/acme serve
summer queue:work	./bin/acme queue:work
summer queue:clear	./bin/acme queue:clear
summer schedule:run	./bin/acme schedule:run
summer route:list	./bin/acme route:list
summer key:generate	./bin/acme key:generate
summer admin:create	./bin/acme admin:create
summer admin:reset-password	./bin/acme admin:reset-password
summer admin:token:create	./bin/acme admin:token:create
summer admin:token:list	./bin/acme admin:token:list
summer admin:token:revoke	./bin/acme admin:token:revoke
summer admin:token:scopes	./bin/acme admin:token:scopes

summer parses no flags of these commands: every flag and argument, including --help, goes to the binary unchanged, and the binary's input is your terminal, so the password prompts of admin:create and admin:reset-password work as usual:

summer serve --addr 127.0.0.1:8123
summer serve --help
summer migrate:rollback --plugin acme.blog
summer admin:create --email admin@example.com --superuser

One leading -- is ignored, so summer serve -- --addr 127.0.0.1:8123 behaves the same as summer serve --addr 127.0.0.1:8123.

When summer receives SIGINT or SIGTERM while the binary runs, it passes the signal on and waits for the binary to shut down, so stopping summer serve with Ctrl+C or kill frees its port.

summer does not rebuild an existing binary before it delegates. Run summer build after you change code, or keep summer dev running. Every other runtime command, such as deferred:purge or the commands your plugins add, is run on the binary directly.

The sections of this chapter

• Setup and maintenance lists every command of the application binary.
• Scaffolding covers summer new, summer build, summer dev and the make: commands.
• Writing commands shows how a plugin adds its own commands.
• Utilities covers the parity and documentation commands of summer.