Foruiman
A modern Procfile runner with process tabs, bounded logs, scrolling, and isolated restarts. Foruiman is a fork of Foreman and retains its MIT license.
Requires Ruby 3.2+ and a POSIX system. CI covers Ruby 3.2, 3.3, 3.4, and 4.0 on Linux.
Install
gem install foruiman
Run
Create a Procfile:
web: bundle exec rails server -p "$PORT"
worker: bundle exec sidekiq
css: yarn build:css --watch
Then start Foruiman:
foruiman
Useful commands:
foruiman start -f Procfile.dev # use another Procfile
foruiman start web # run one process
foruiman start --no-tui # stream plain logs
foruiman run bin/rails console # one-off command with the app environment
foruiman start --exit-on any # stop the group when a process exits
foruiman check # validate without starting
foruiman --version
The TUI opens when stdin and stdout are terminals. Otherwise, Foruiman streams plain logs and exits when the processes finish. Processes run independently, and restarting one process does not interrupt the others.
Each TUI process gets its own open terminal input, so asset builders using their
default --watch mode stay alive. Select a process and press i to type into a
debugger such as Pry, Byebug or IRB. Edit in the input bar, press Enter to send,
and Ctrl-X to return to Foruiman. Arrow keys edit and recall commands; Ctrl-C
interrupts the selected process. Debugger tab completion is not forwarded.
Press s to stop the selected process, or all processes from all; on a stopped
process tab, s starts it again.
The aggregate all tab uses shortcut 0. A process named all has its own
numbered tab and independent controls. USR1 and USR2 sent to Foruiman are forwarded
to every child process group for application-defined handling.
In plain mode, children inherit stdin, including terminal input. Multiple children reading stdin share that stream; use TUI input controls to target one process.
Options
| Option | Default | Purpose | ||
|---|---|---|---|---|
-f, --procfile FILE |
Procfile |
Procfile to run | ||
-d, --root DIR |
Procfile directory | Working directory | ||
-e, --env FILES |
.env |
Comma-separated files, loaded in order instead of .env |
||
--no-dotenv |
.env enabled |
Skip .env |
||
-p, --port PORT |
Environment PORT, then 5000 |
Base port; entries increment by 100 | ||
-t, --timeout SECONDS |
5 |
Grace period before forced shutdown | ||
| `--exit-on all\ | any\ | failure` | all |
Keep peers running, stop on any exit, or stop on failure |
--log-lines N |
10000 |
Retained records per process and in all |
||
--no-tui |
TUI when interactive | Force plain output |
Set defaults in a .foreman YAML file in the invocation directory; CLI flags
override them. See compatibility and migration notes for
path rules, supported settings, and changes from 0.2.
Keyboard
| Key | Action |
|---|---|
Tab / Shift-Tab, Left / Right, h / l |
Change tab |
1–9, 0 |
Select a process or all |
Up / Down, k / j |
Scroll |
| PageUp / PageDown, Ctrl-U / Ctrl-D | Scroll a page |
Home / g |
Jump to oldest retained log |
End / G / f |
Follow new output |
| Space | Pause or resume following |
i / Ctrl-X |
Open command input / return to Foruiman |
r |
Restart the selected process, or all from all |
R |
Restart all processes |
s / S |
Start/stop selected (s on all stops all) / stop all |
? / Escape |
Toggle help / close help |
q / Ctrl-C |
Stop processes and quit |
Documentation
Development
bundle install
bundle exec rspec
bundle exec rubocop
gem build foruiman.gemspec
bundle exec ruby script/smoke_gem.rb
Release
Releases use RubyGems trusted publishing. Configure the publisher once with
repository Nuzair46/foruiman, workflow release.yml, and environment release.
To publish, update lib/foruiman/version.rb and CHANGELOG.md, then run
bundle install to update the version in Gemfile.lock. Commit all three files
to main; CI requires the lockfile to match the gem version. Open the
Release workflow,
choose Run workflow, and select main. GitHub Actions runs the full CI suite,
creates the version tag, and publishes the gem to RubyGems.org.