demo.md

Reset

Reset demo directory

mkdir -p /tmp/talo # change this path for your system
cd /tmp/talo       # same here
rm -r export
rm -r docs
rm .talo
clear

Basics

Initialize ADR with built-in template (You can use the --template-path option to specify a custom template)

clear
talo init adr --location docs/adr

Initialize RFC with built-in template

clear
talo init rfc --location docs/rfc

List all initialized record types

clear
talo list

List all registered ADRs
(adr command creates the first ADR automatically)

clear
talo list adr

List all registered RFCs (empty list)

clear
talo list rfc

Let's add some ADRs:

clear
talo add adr --title "Use event-based architecture" --status Accepted
talo add adr --title "Use MS SQL database" --status Accepted

Create a new ADR that supersedes a previous ADR (number 3):

clear
talo add adr --title "Use PostgresSQL for all database needs" --status Accepted --supersedes 3

Let's list ADRs again to see how the statuses look:

clear
talo list adr

Observe the contents of the new ADR
(it has two rows in the status table)

clear
cat docs/adr/ADR0004-use-postgressql-for-all-database-needs.md

If you want to use a custom template for a specific record, you can do so:

clear
talo add adr --title "Use GPL-3.0-or-later as license" --status Accepted --from-template templates/differentadr.md

The list command also has a flag to display the file path:

clear
talo list adr --include-file-path

Let's check the contents of newly created ADR to confirm that talo used the given custom template:

clear
cat docs/adr/ADR0005-use-gpl-3.0-or-later-as-license.md

Updating status

You can use the revise command to update the status of a record. You need to specify the number and the new status:

clear
talo revise adr --number 2 --status Obsolete

Let's see how that looks:

clear
talo list adr

Linking

Some more ADRs first:

clear
talo add adr --title "Store configuration in files" --status Accepted
talo add adr --title "Use dashes in file names" --status Accepted

talo can link two records to each other. For example:

clear
talo link adr --source 7 --source-status "Amends" --destination 6 --destination-status "Amended by"

This will update the status tables of both records.

clear
talo list adr

Exporting

You can use the export command to export your records as HTML. This can be useful if you want to deploy them to a web site so that a wider audience can access them.

clear
talo export --help

It will by default export all records. But you can specify a type to limit it:

clear
talo export --types adr

Let's check the output (note the 'index.html' file):

clear
ls -al ./export/adr

And browse the files:

firefox -new-window ./export/adr/index.html

Configuration

If you want to use a custom template for your records, you can configure that per record type:

clear
talo config adr --template-path templates/differentadr.md

Create your own record type

You can use the config add command to create a custom record type:

clear
talo config add --name prd --location docs/prd --template-path templates/prd.md --description "Product Requirement Document"

clear
talo list

talo has now registered a new command: prd
You can perform all the same operations with it.
Let's add a new record using the custom type:

clear
talo add prd --title "Shopping cart experience" --status "Under review"

And list all records of this type:

clear
talo list prd

Help

clear
talo --help

clear
talo add adr --help

clear
talo config --help

clear
talo link rfc --help

clear
talo --version