Help language development. Donate to The Perl Foundation

Tomtit cpan:MELEZHIK last updated on 2019-01-16



Tomtit - Perl6 task runner with dozens of plugins.

Build Status

Build Status


zef install Tomtit


You need to bootstrap your system to start using tomtit, it's a one time operation, where you install Sparrow which is underlying tomtit runner.

tom --bootstrap 


tom $action|$options $thing

Run scenario:

tom $scenario

Default action (list of scenarios):


List available scenarios:

tom --list

Get help:

tom --help

Show the last executed scenario:

tom --last

Clean tomtit cache:

tom --clean


tom --list

[scenarios list]

tom test        

Defining scenarios

Tomtit scenarios are just Sparrowdo scenarios you create in .tom directory, which is base Tomtit directory:

mkdir .tom/
nano .tom/build.pl6
nano .tom/test.pl6
nano .tom/install.pl6

You want to ignore tomtit cache which commit files to SCM:

git add .tom/
echo .tom/.cache >> .gitignore

Scenario example

You can do anything, allowable through Sparrowdo API, like:

cat .tom/example.pl6

# you can Sparrowdo shortcuts 
# to create files and directories

file 'passwords.txt', %( content => "super secret" );

directory '.cache';

# or restart service

service-restart "web-app";

# or you can run a certain sparrow plugin
# by using task-run function:

task-run 'my task', 'plugin', %( foo => 'bar' );

# for example, to set git repository, 
# use git-base plugin:

task-run "set git", "git-base", %(
  email => '',
  name  => 'Alexey Melezhik',
  config_scope => 'local',
  set_credential_cache => 'on'

And so on.

As result you minimize code to execute many typical tasks.

Running with sudo

Some scripts sudo for task execution, to switch tomtit in superuser mode just add --sudo flag when running scenario:

tomtit --sudo $scenario


Profiles are predefined sets of tomtit scenarios. To start using scenarios from profile you say:

tom --profile $profile

Once the command is executed the profile scenarios get installed to the base tomtit directory.

To list available profiles say this:

tom --profile

To list profiles scenarios say this:

tom --list --profile $profile

You can install selected scenario from profile by using special notation:

tom --profile $profile@$scenario

For example to install commit scenario from git profile:

tom --profile git@commit 

Portable profiles

Tomtit exposes API to create portable profiles as regular Perl6 modules.

You should create Perl6 module in Tomtit::Profile namespace with the our function profile-data, returning Hash with scenarios data.

For example:


use v6;

unit module Tomtit::Profile::Pets:ver<0.0.1>;

our sub profile-data () {

  my %a is Map  = (
    cat   => (slurp %?RESOURCES<cat.pl6>.Str),
    dog   => (slurp %?RESOURCES<dog.pl6>.Str),
    fish  => (slurp %?RESOURCES<fish.pl6>.Str)


The above module defines Tomtit::Profile::Pets profile with 3 scenarios cat, dog, fish installed as module resources:


Now we can install it as regular Perl6 module and use through tom:

zef install Tomtit::Profile::Pets

Once module is installed we can install related profile. Note that we should replace :: by - (*) symbols when refering to profile name.

tom --list --profile Tomtit-Profile-Pets

load portable profile Tomtit::Profile::Pets as Perl6 module ...
[profile scenarios]
Tomtit::Profile::Pets@cat       installed: False
Tomtit::Profile::Pets@dog       installed: False
Tomtit::Profile::Pets@fish      installed: False

tom --profile Tomtit-Profile-Pets

install Tomtit::Profile::Pets@cat ...
install Tomtit::Profile::Pets@dog ...
install Tomtit::Profile::Pets@fish ...

(*) Tomtit require such a mapping so that Bash completion could work correctly.

Removing scenarios

To remove installed scenario say this:

tom --remove $scenario

Edit scenario source code

Use --edit to create scenario from the scratch or to edit existed scenario source code:

tom --edit $scenario

Getting scenario source code

Use --cat command to print out scenario source code:

tom --cat $scenario

Use --lines flag to print out with line numbers.


You can define tomtit environments/configurations as Sparrowdo configuration files.

Create configuration file at .tom/conf directory:


    name => "tomtit",
    who-are-you => "smart bird"


Run tomtit.

It will pick the .tom/env/config.pl6 and read configuration from it, variables will be accessible as config Hash, inside tomtit scenarios:

my $name = config<name>;
my $who-are-you = config<who-are-you>;

To define named configuration ( environment ), simply create .tom/env/config{$env}.pl6 file and refer to it through --env=$env parameter:

nano .tom/env/

tom --env=prod ... other parameters here # will run with production configuration

You can run editor for environment configuration by using --edit option:

tom --env-edit test    # edit test enviroment configuration

tom --env-edit default # edit default configuration

You can activate environment by using --env-set parameter:

tom --env-set prod    # set prod environment as default
tom --env-set         # to list active (current) environment
tom --env-set default # to set current environment to default

To view environment configuration use --env-cat command:

tom --env-cat $env

You print out the list of all environments by using --env-list parameters:

tom --env-list

Tomtit cli configuration

You can set tomtit configuration in ~/tom.yaml file:

# list of portable tomtit profiles,
# will be available through Bash completion


  - Tomtit-Foo
  - Tomtit-Bar
  - Tomtit-Bar-Baz

# you can also setup some tomtit cli options here


  quiet: true


    --verbose   # run scenario in verbose mode
    --quiet,-q  # run scenario in less verbose mode

Bash completion

You can install Bash completion for tom cli.

tom --completion
source  ~/


Alexey Melezhik

Thanks to

God Who gives me inspiration in my work