rails_routes

Every HTTP route of the app, generated by the app itself with bin/rails routes --expanded, so engines and route concerns resolve exactly as Rails sees them.

  1. Parameters
  2. Example
  3. How it runs
  4. Routes without booting
  5. When routes can’t be listed

Parameters

Parameter Type Description
filter string Optional. Case-insensitive substring matched against the route name, path, verb and controller#action

Example 

// rails_routes { "filter": "comments" }
{
  "source": "routes_expanded.txt",
  "total": 7,
  "count": 2,
  "routes": [
    {
      "name": "post_comments",
      "verb": "POST",
      "path": "/posts/:post_id/comments(.:format)",
      "action": "create",
      "source_location": "config/routes.rb:3",
      "controller": "comments",
      "controller_action": "comments#create"
    },
    {
      "name": "post_comment",
      "verb": "DELETE",
      "path": "/posts/:post_id/comments/:id(.:format)",
      "action": "destroy",
      "source_location": "config/routes.rb:3",
      "controller": "comments",
      "controller_action": "comments#destroy"
    }
  ]
}

total is the number of routes in the app, and count is the number that matched the filter.

How it runs

The tool runs bin/rails routes --expanded in --root, using the Ruby that runs rails-agent-kit, with Bundler’s environment cleared so the app loads its own Gemfile. If your app needs a different Ruby, use RAILS_AGENT_KIT_ROUTES_COMMAND or a saved dump (below). The command times out after 60 seconds by default (RAILS_AGENT_KIT_ROUTES_TIMEOUT).

A relative --routes-file path is resolved against --root.

Routes without booting

If your app can’t boot locally (it needs a database, secrets or Docker), you have two options.

Point the server at a saved dump:

bin/rails routes --expanded > tmp/routes.txt
rails-agent-kit --root . --routes-file tmp/routes.txt

Run the routes command somewhere else, for example in your Docker Compose service:

RAILS_AGENT_KIT_ROUTES_COMMAND="docker compose exec -T web bin/rails routes --expanded" \
  rails-agent-kit --root /path/to/your/rails/app

When routes can’t be listed

If the command fails, times out or prints nothing it can parse, the tool doesn’t fail. It returns routes_unavailable: true, a message explaining why (with the tail of the error output) and how to fix it, and the raw config/routes.rb as routes_rb, so the agent still has something to read.

{
  "routes_unavailable": true,
  "message": "Could not list routes: ... Falling back to the raw config/routes.rb (no route expansion, helpers or engine routes). Tip: run `bin/rails routes --expanded > tmp/routes.txt` and start the server with --routes-file tmp/routes.txt.",
  "fallback_source": "config/routes.rb",
  "routes_rb": "Rails.application.routes.draw do\n  resources :posts do\n ..."
}