pelican/README.asciidoc

= Pelican
:toc:
:toclevels: 1
:toc-title: Contents

== Overview

**This project is in ALPHA state and is not ready for production use yet.**

Pelican is a simple Kanban board for your terminal.
Data is stored in a https://github.com/etcd-io/bbolt[BoltDB] database.
Pelican does not make any assumptions to the path of the database file;
instead the user is expected to specify the path when running the application.

== Installation

=== Requirements

==== Go

A minimum version of Go 1.21.0 is required for installing spruce.
Please go https://go.dev/dl/[here] to download the latest version.

==== Mage (Optional)

The project includes a https://codeflow.dananglin.me.uk/apollo/pelican/src/branch/main/magefiles/mage.go[magefile]
for automating the build and installation of the binary.
You can visit the https://magefile.org[website] for instructions on how to install Mage.

=== Install with Mage

You can install pelican with Mage using the following commands:
[source,console]
----
git clone https://codeflow.dananglin.me.uk/apollo/pelican.git
cd pelican
mage install
----

The default install prefix is set to `/usr/local` so pelican will be installed to `/usr/local/bin/pelican`.
If you want to change the install prefix you can set the `PELICAN_INSTALL_PREFIX` environment variable
before installing.
[source,console]
----
PELICAN_INSTALL_PREFIX=~/.local mage install
----

=== Install with Go

If your `GOBIN` directory is included in your `PATH` then you can install Pelican with Go.

[source,console]
----
git clone https://codeflow.dananglin.me.uk/apollo/pelican.git
cd pelican
go install ./cmd/pelican
----

== Running Pelican

To create a new Kanban project with Pelican, simply run the following command:
[source,console]
----
pelican project.pelican
----

This will create a new BoltDB database file called `project.pelican` in your current directory
and initialises the database with an empty project.

== Keybindings

[%header,cols=2*]
|===
|Key
|Action

|`CTRL + q`
|Quit the application

|`c`
|Create a new card

|`CTRL + d`
|Delete a card

|`m`
|Move a card from one column to another (press `Enter` to confirm your selection).

|`Enter`
|View the details of a card (press `ESC` to go back to the main board).
|===

== Inspiration

https://github.com/witchard/toukan[The toukan project]