Your First Angreal

This project is available under the example folder of the git repository.

This a very simple project for taking meeting minutes !

We have some basic requirements for this template :

  • on creation a folder with the meeting name will be created
  • on creation a file that introduces us to the reason the meetings exist as an initial README.
  • a task to take minutes using an editor

Template Layout

Based on the above planned requirements we’ll need files and folders created as follows :

├── angreal.toml
└── {{ name }}
    ├── .angreal
    │   ├──
    │   └──


The angreal.toml file tells angreal what variables it needs to template and provides default values for them. Our template will have the following variables:

  • name
  • cadence
  • standing_agenda

The is just meant to be a highlevel description of the meeting so you can remember why you’re there every week.

# {{ name }}

## Cadence

{{ cadence }}

## Standing Agenda

{{ standing_agenda }}

Optional: In this very trivial example, not much happens after the folder structure is created so the init isn’t required.

def init():
    print("Initializing {{ name }} !")

Angreal tasks must be a function in a python file that starts with task_ in the .angreal folder.

import angreal

import datetime
import os
import subprocess
import tempfile

@angreal.command(name='take-notes', about='Take notes for our meeting')
@angreal.argument(name='now',long='now', takes_value=False)
def angreal_cmd(now=False):
    create a file for taking minutes
    file_name ='%Y-%m-%d-%H-%M')

    # We're going to assume that you're running on ubuntu
    # which has a binary called "editor" that will launch your
    # default terminal editor. If you need something else - set the environment
    # variable "EDITOR" to the appropriate command
    editor = os.environ.get('EDITOR','editor')

    # Create our default file template using the current time as a header
    (fd, path) = tempfile.mkstemp()
    with open(fd, 'w') as default:
        print('# {}'.format(file_name), file=default)

    # We want to start writing now if we're able
    if now and editor:'{} {}'.format(editor,path), shell=True)

    # Send the finalized contents of the temporary file to the actual file
    with open(file_name+'.md', 'a') as dst:
        with open(path,'r') as src:

    # Clean up behind our selves

A brief explanation of this code: - import angreal and other libraries - decorate a function with the command - we decorate the same function with an argument

The function itself:

  • determines the current date/time
  • tries to get an EDITOR variable from the environment, falling back to the editor command from Ubuntu
  • if you pass the --now argument, opens a temporary file using your editor
  • saves the notes taken to a file with the date and time the minutes were started.

Using our Angreal

  1. Initialize our template.
$ angreal init docs/content/tutorials/meeting_notes

cadence? ["weekly"]
name? ["another_meeting"]
> Hall of the Tower
standing_agenda? ["Complaints"]
> Discussing embroidery and fine turned calves

Initializing Hall of the Tower !
$ tree 'Hall of the Tower'
Hall of the Tower
$ cat Hall\ of\ the\ Tower/                                                                                                            ─╯
# Hall of the Tower

## Cadence


## Standing Agenda

Discussing embroidery and fine turned calves.
  1. What commands do i have access to ?
$ cd 'Hall of the Tower'
$ angreal

angreal 2.0.0-rc.1

    angreal <SUBCOMMAND>

    -h, --help       Print help information
    -V, --version    Print version information

    help          Print this message or the help of the given subcommand(s)
    init          Initialize an Angreal template from source.
    take-notes    Take notes for our meeting
  1. How do i use take-notes ?
$ angreal take-notes --help


    create a file for taking minutes

    take-notes [OPTIONS]

    -h, --help
            Print help information

            open editor immediately

Lets take some minutes, right now

$ export EDITOR='vim'
$ angreal take-minutes --now

This will open an editor (vim if you set the EDITOR variable) write a note.

$ ls                                                                                                                                            ─╯