V2.0: Commands

Hanami provides a command line interface with helpful commands for generating a new application, starting a console, starting a development server, displaying routes and more.

Gem commands

After an initial install via gem install hanami, hanami offers two commands:

$ hanami --help

  hanami new APP         # Generate a new Hanami app
  hanami version         # Hanami version

hanami new

Generates a Hanami application with the given APP name, in a new directory from the current location.

$ hanami new bookshelf # generates a new Bookshelf application in ./bookshelf
$ hanami new my_app # generates a new MyApp application in ./my_app

hanami version

Displays the Hanami version of the currently installed gem.

$ hanami version

Project commands

When executed from within a hanami project, hanami offers a different set of commands.

These commands can be listed using the --help flag.

$ bundle exec hanami --help

  hanami console                              # Start app console (REPL)
  hanami generate [SUBCOMMAND]
  hanami middleware                           # Print app Rack middleware stack
  hanami routes                               # Print app routes
  hanami server                               # Start Hanami app server
  hanami version                              # Print Hanami app version

hanami console

Starts the Hanami console.

$ bundle exec hanami console


This command accepts an engine argument that can start the console using IRB or Pry.

$ bundle exec hanami console --engine=irb # (the default)
$ bundle exec hanami console --engine=pry

hanami generate

Hanami 2.0 provides two generators, one for actions and one for slices.

$ bundle exec hanami generate --help

  hanami generate action NAME
  hanami generate slice NAME

These can be invoked as follows:

$ hanami generate action books.show
$ hanami generate slice api

See the actions and slices guides for example usage.

hanami middleware

Displays the Rack middleware stack as currently configured.

$ bundle exec hanami middleware

/    Dry::Monitor::Rack::Middleware (instance)
/    Rack::Session::Cookie
/    Hanami::Middleware::BodyParser

This command accepts a --with-arguments option that will include initialization arguments:

$ bundle exec hanami middleware --with-arguments

/    Dry::Monitor::Rack::Middleware (instance) args: []
/    Rack::Session::Cookie args: [{:key=>"my_app.session", :secret=>"secret", :expire_after=>31536000}]
/    Hanami::Middleware::BodyParser args: [:json]

hanami routes

Displays your application’s routes.

$ bundle exec hanami routes

GET     /                             home.index                    as :root
GET     /books                        books.index
GET     /books/:id                    books.show
POST    /books                        books.create

By default, routes are displayed in “human friendly” format. Routes can be inspected in csv format via the format option:

$ bundle exec hanami routes --format=csv


hanami server

Launches hanami’s development server for developing against your application locally.

$ bundle exec hanami server

14:33:28 - INFO - Using Guardfile at bookshelf/Guardfile.
14:33:28 - INFO - Puma starting on port 2300 in development environment.
14:33:28 - INFO - Guard is now watching at 'bookshelf'
[43884] Puma starting in cluster mode...
[43884] * Puma version: 6.0.0 (ruby 3.1.0-p0) ("Sunflower")
[43884] *  Min threads: 5
[43884] *  Max threads: 5
[43884] *  Environment: development
[43884] *   Master PID: 43884
[43884] *      Workers: 2
[43884] *     Restarts: () hot () phased
[43884] * Preloading application
[43884] * Listening on
[43884] Use Ctrl-C to stop

This server is for local development only. In production, use the following to start your application serving web requests with Puma:

$ bundle exec puma -C config/puma.rb

hanami version

Prints the version of the installed hanami gem.

$ bundle exec hanami version