Devtool: nested subcommands with hooks and groups

Copy Markdown View Source

A multi-command developer toolkit. devtool server start, devtool db migrate, etc. Exercises subcommand nesting, a persistent lifecycle hook, per-command hooks, mutually exclusive option groups, choices, and cross-param validation.

Full runnable project: examples/devtool/.

Layout

devtool
  server
    start   -- starts the dev server
    stop    -- stops it
  db
    migrate -- runs migrations
    seed    -- seeds the database

The root

defmodule Devtool.CLI do
  use Cheer.Command

  command "devtool" do
    about "Developer toolkit"
    version "0.1.0"

    persistent_before_run fn args ->
      Map.put(args, :start_time, System.monotonic_time(:millisecond))
    end

    subcommand Devtool.Server
    subcommand Devtool.Db
  end

  def main(argv) do
    Cheer.run(__MODULE__, argv, prog: "devtool")
  end
end

persistent_before_run declared on the root propagates to every descendant. Every leaf-command handler sees args[:start_time] regardless of which subcommand was invoked.

A branch: server

defmodule Devtool.Server do
  use Cheer.Command

  command "server" do
    about "Server management"

    subcommand Devtool.Server.Start
    subcommand Devtool.Server.Stop
  end
end

Branches have no run/2 -- cheer routes to children automatically.

A leaf with a group and a validator: server start

defmodule Devtool.Server.Start do
  use Cheer.Command

  command "start" do
    about "Start the dev server"

    option :port, type: :integer, short: :p, default: 4000, env: "DEV_PORT",
      validate: fn p -> if p in 1024..65535, do: :ok, else: {:error, "port must be 1024-65535"} end,
      help: "Port to listen on"

    option :host, type: :string, short: :H, default: "localhost", help: "Bind address"

    group :protocol, mutually_exclusive: true do
      option :http,  type: :boolean, help: "Use HTTP"
      option :https, type: :boolean, help: "Use HTTPS"
    end
  end

  @impl Cheer.Command
  def run(args, _raw) do
    protocol = if args[:https], do: "https", else: "http"
    IO.puts("Starting server at #{protocol}://#{args[:host]}:#{args[:port]}")
    IO.puts("(started in #{elapsed(args)}ms)")
  end

  defp elapsed(%{start_time: t}), do: System.monotonic_time(:millisecond) - t
  defp elapsed(_), do: 0
end

Passing both --http --https produces a friendly error from the group constraint.

A leaf with before/after hooks: db migrate

defmodule Devtool.Db.Migrate do
  use Cheer.Command

  command "migrate" do
    about "Run database migrations"

    option :target,  type: :string, short: :t, help: "Target migration version"
    option :dry_run, type: :boolean, help: "Show what would be run without applying"

    before_run fn args ->
      IO.puts("Connecting to database...")
      args
    end

    after_run fn result ->
      IO.puts("Done.")
      result
    end
  end

  @impl Cheer.Command
  def run(args, _raw) do
    prefix = if args[:dry_run], do: "[dry run] ", else: ""

    case args[:target] do
      nil    -> IO.puts("#{prefix}Running all pending migrations...")
      target -> IO.puts("#{prefix}Migrating to version #{target}...")
    end
  end
end

Hooks run in order: root persistent_before_run, then this command's before_run, then run/2, then after_run.

A leaf with choices and cross-param validation: db seed

defmodule Devtool.Db.Seed do
  use Cheer.Command

  command "seed" do
    about "Seed the database"

    option :env, type: :string, default: "development",
      choices: ["development", "staging", "test"],
      help: "Target environment"

    option :clean, type: :boolean, help: "Truncate tables before seeding"

    validate fn args ->
      if args[:clean] && args[:env] == "staging" do
        {:error, "cannot use --clean with staging environment"}
      else
        :ok
      end
    end
  end

  @impl Cheer.Command
  def run(args, _raw) do
    if args[:clean], do: IO.puts("Truncating tables...")
    IO.puts("Seeding #{args[:env]} database...")
  end
end

Type coercion, choices validation, and the cross-param validate all run before run/2.

Run it

cd examples/devtool
mix deps.get

mix run -e 'Devtool.CLI.main(["server", "start", "--port", "8080", "--https"])'
# Starting server at https://localhost:8080
# (started in 0ms)

mix run -e 'Devtool.CLI.main(["db", "migrate", "--target", "20240101"])'
# Connecting to database...
# Migrating to version 20240101...
# Done.

mix run -e 'Devtool.CLI.main(["db", "seed", "--env", "staging", "--clean"])'
# error: cannot use --clean with staging environment

mix run -e 'Devtool.CLI.main(["server", "--help"])'

What it shows

  • Nested command tree with branches that have no run/2.
  • Persistent lifecycle hook propagated from the root to every leaf.
  • Per-command before_run / after_run hooks.
  • Mutually exclusive option group with auto-generated error message.
  • Choices for string-enum options.
  • Cross-param validator enforcing a rule across two options.
  • Env var fallback combined with a validator.

See also