Ruby gem
caml turns well-documented YAML tasks into a runnable CLI.
make and just inspired it, but the tasks live in YAML.
Give a task a name, a desc, and an execute shell command,
then run caml to list every task with its description. caml does not
track file timestamps, so it never skips work that is already done. Treat it as a
task runner, not a build system.
caml ships as a Ruby gem and needs Ruby 3.0 or newer.
gem install camlTo pin caml to one project instead, add it to that project's Gemfile.
gem 'caml'
Run caml init first, because it writes the starter
caml.yaml that the next two commands read.
gem install caml
caml init # scaffold a starter caml.yaml
caml # list tasks
caml hello # run the starter task
If a caml.yaml already exists, caml refuses to overwrite it and
exits 1. Rename the old file, then retry.
The scaffold holds one task, hello. Open the file, replace that task
with a real one, then read the reference for every key a
task accepts.
You declare commands. caml builds the CLI around them on every run.
desc, and an execute shell command. It needs nothing else.caml.yaml and registers the commands each time you invoke it. No build step. No cache to clear.Each topic below shows the YAML first and then explains it, so you can skim the blocks and stop where the shape matches your problem. Copy any example as it stands.
test:
desc: Run the test suite
execute: bundle exec rspec
Each top-level key is a task. A task has a desc and an
execute shell command. Run caml or caml help
to list every task with its description.
setup:
desc: Install and migrate
execute:
- bundle install
- bin/rails db:migratePass a list to run several steps. Steps run with fail-fast semantics, so the first non-zero exit aborts the task.
greet:
desc: Say hello to someone
args:
name:
desc: Person to greet
type: string
execute: echo Hello, {{name}}!caml greet world
# Hello, world!
Positional arguments substitute into the execute template through
{{name}}. caml shell-escapes every value it substitutes.
build:
desc: Build the project
opts:
target:
type: string
default: dist
aliases:
- t
desc: Output directory
verbose:
type: boolean
aliases:
- v
desc: Print verbose output
execute: make build TARGET={{target}}caml build --target release
caml build -t release -v
An option is a flag with a type. It also takes optional
aliases, a default value, and an override
execute.
start:
desc: Start the app
opts:
background:
type: boolean
aliases:
- b
desc: Run as a daemon
execute: app start --daemon
execute: app startcaml start # app start
caml start --background # app start --daemon
When a boolean option carries its own execute, that command runs
instead of the task's default.
test:
desc: Run the test suite
aliases:
- t
execute: bundle exec rspeccaml t # same as caml testAdd shortcut names for a task with aliases.
test:
desc: Run tests
execute: bundle exec rspec
lint:
desc: Check style
execute: bundle exec rubocop
ci:
desc: Lint and test
needs:
- lint
- testcaml ci # runs lint, then test
A task can declare prerequisites with needs. Dependencies run in
declared order, each at most once per invocation, and a failure aborts the run.
A task with only needs: and no execute is a pure
orchestrator, which is useful for grouping.
caml walks up from the current directory to find a
caml.yaml, just like git. So you can run it from any
subdirectory of your project.
If no caml.yaml sits in the current directory or any parent, caml
says so and exits 1. Run caml init to scaffold one.
| Command | Description |
|---|---|
| caml init | Scaffold a starter caml.yaml |
| caml --version | Print the installed version |
| caml help [cmd] | Show help for a specific task (its args and opts) |