Skip to content

Using the CLI

August has command documentation within the CLI itself, but this page provides more detail for specifics.

august info

0.1.0

Provides information about the current August install and the amount of modules in the current directory and global module directory.

august info
Resulting output:

Note

The formatting looks a bit off in these docs due to the Material for MkDocs syntax highlighter. It looks normal in a terminal. Many thanks to the work of @Nukesor on the crate, comfy-table.

╭────────────────┬───────────────────────────────────────────────╮
│ Package Name   ┆ august-build                                  │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Author(s)      ┆ Hayden Brown <scratchcat458@gmail.com>        │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Version        ┆ 0.2.1                                         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Documentation  ┆ https://august-build.web.app                  │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Repository     ┆ https://github.com/ScratchCat458/august-build │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Global Modules ┆ 0 in ~/.august/modules/                       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Local Modules  ┆ 4 in current directory                        │
╰────────────────┴───────────────────────────────────────────────╯

Execution

There are three commands used for executing build scripts, two of which are tied to pragmas.

august test

0.1.0

Runs the task assigned to #pragma test.

august test

Resulting output: 

Hello, World!


@main

#pragma test hello

Task hello {
    print("Hello, World!")
}

august build

0.1.0

Runs the task assigned to #pragma build.

august build

Resulting output: 

Hello, World!


@main

#pragma build hello

Task hello {
    print("Hello, World!")
}

august run <TASK>

0.1.0

Runs a task by name.

august run hello

Resulting output: 

Hello, World!


@main

Task hello {
    print("Hello, World!")
}

Verification

These commands do not run anything but can help with check that a script works before running or deploying to CI.

august inspect

0.1.1

Lists the contents of a build script and any linked modules in tabular form.

august inspect

Resulting output:

Note

The formatting looks a bit off in these docs due to the Material for MkDocs syntax highlighter. It looks normal in a terminal. Many thanks to the work of @Nukesor on the crate, comfy-table.

╭─────────────────────┬─────────────────────────╮
│ Property            ┆ Contents                │
╞═════════════════════╪═════════════════════════╡
│ Namespace           ┆ main                    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Pragma              ┆ Test --> None           │
│                     ┆ Build --> build         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Tasks               ┆ - build                 │
│                     ┆                         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Command Definitions ┆ - localcmddef           │
│                     ┆ - mycmd from ext_module │
│                     ┆                         │
╰─────────────────────┴─────────────────────────╯

@main

#link ext_module
#pragma build build

Task build {
  print("This message is from an internal command!");
  localcmddef;
  ext_module.mycmd;
}

cmddef localcmddef {
  print("This message is from a locally defined command!");
}

@ext_module

cmddef mycmd {
  print("This message is from an externally defined command!");
}

august check

0.1.0

Runs the build script and linked modules through the parser without running anything.

Script Specification

For commands that require a script to be run, the default file path is main.august. However this can be changed using the -s flag.

august build -s <FILE_PATH>
This applies for:

  • august test
  • august build
  • august run <TASK>
  • august check
  • august inspect

Command Line Autocompletion

Autocompletion is avaliable August thanks to clap_complete. This provideds support for the following shells:

  • Bash
  • Fish
  • Zsh
  • Powershell
  • Elvish

This works by placing the generated autocomplete in standard out. The contents must be copied into a file and into the config for your specific shell.

august completions bash > /usr/share/bash-completion/completions/august.bash

august completions fish > ~/.config/fish/completions/august.fish

august completions zsh > /usr/share/zsh/functions/Completions/Unix/_august


august completions powershell > ~\Documents\WindowsPowerShell\august.ps1
Add the following line to your Powershell profile: 
. ~\Documents\WindowsPowerShell\august.ps1