Command line

This section will cover the command line parameters, you can use to influence the behaviour of TaskFalcon.

Overview

You can get a brief overview of all available parameters by running TaskFalcon without any parameter:

> falcon
Usage: falcon [options] <filename>

See https://taskfalcon.org/doc/command_line/index.html for more details and examples.

  -abort-on-error
        Aborts scheduling if an error was reported during validation
  -abort-on-warning
        Aborts scheduling if a warning was reported during validation
  -colors string
        Import custom color table from file. Exports default colors if file does not exist
  -end string
        Sets a end date for all output formats. Format is either YYYY-MM-DD (e.g. 2020-09-20) for absolute days or +/-<duration> (e.g. +3w) for a time relative to TODAY
  -export-charts string
        Comma separated list of charts to export. Supports "gantt", "gantt-with-resources", "resources", "resources-with-tasks" (default "gantt,gantt-with-resources,resources,resources-with-tasks")
  -export-csv
        Export results to CSV file
  -export-resource-slips
        Exports a resource slip for each resource, which shows the list of tasks assigned to it
  -export-xlsx
        Export results to XLSX (Excel 2007+) file
  -h    Shows this help
  -max-depth int
        Renders only tasks with a maximum hierarchical depth (default -1)
  -no-charts
        Prevents the generation of rendered chart images. Same as -export-charts "" (empty)
  -no-tasks
        Renders only groups and milestones but no tasks. Automatically enables -show-group-resources
  -no-updates
        Ignores updates in the project - just schedules the baseline
  -prefix string
        Limits rendering only tasks which IDs begin with a prefix
  -scale string
        Sets the rendering scale. One of DAY|WEEK|MONTH|YEAR
  -show-closed-tasks
        Show tasks that have been completed in the past
  -show-dependencies
        Show dependencies of all tasks/groups/milestones
  -show-efforts
        Shows efforts in an additional column
  -show-effortsleft
        Shows remaining task efforts for today in an additional column
  -show-ends
        Shows end dates in a separate column
  -show-group-resources
        Renders resource summaries for task groups
  -show-ids
        Shows Task/Milestone/Group/Resource IDs in the output instead of names
  -start string
        Sets a start date for all output formats. Format is either YYYY-MM-DD (e.g. 2020-09-20) for absolute days or +/-<duration> (e.g. +3w) for a time relative to TODAY
  -sub-projects
        Instead of the main project, render charts for each imported sub-project
  -today string
        Sets the current date for determining efforts left and rendering the date line. Format is YYYY-MM-DD (e.g. 2020-09-20)
  -v    Prints version number

TaskFalcon v0.9.9. ©2020-2021 Marc Müller. All rights reserved.

Parameters -export-charts and -no-charts

since v0.9.9

This parameter allows selective rendering of those four chart types.
It allows combining those charts through a comma separated list (no whitespace) in any order. See examples below.

  1. gantt:
    Renders a basic GANTT chart with task-groups, tasks and milestones: GANTT chart

  2. gantt-with-resources:
    Renders a GANTT chart with assigned resources for each task: GANTT chart

  3. resources:
    Renders a resource utilisation chart: GANTT chart

  4. resources-with-tasks:
    Renders a Resource utilisation chart with a list of assigned tasks for each resource: GANTT chart

Example

# This renders only a GANTT chart
falcon -export-charts gantt example.yaml 

# This renders resource chart and a GANTT chart with resources
falcon -export-charts gantt-with-resources,gantt example.yaml

# The default setting renders all available charts, hence the next 2 lines result in the same output
falcon -export-charts gantt,gantt-with-resources,resources,resources-with-tasks example.yaml
falcon example.yaml

# The next 2 lines will both renders no charts at all (e.g. only useful when used with other export options like "-export-csv")
falcon -export-charts "" example.yaml
falcon -no-charts example.yaml

Parameter -export-resource-slips

since v0.9.7

This parameter will export an overview of all related tasks for each available resource.

The content is identical to the generated project file <project-name>.resources-with-tasks.png, but it will create one separate chart for each resource and each file will only show tasks this resource will be working on.

Example

falcon -today 2020-06-01 -export-resource-slips example.yaml

GANTT chart

GANTT chart


Parameter -prefix

since v0.8.1

A prefix allows you to create a chart for only a limited branch of your project plan. The required parameter is the beginning of a fully qualified ID (see Task/Milestones/Groups).

Example

falcon -today 2020-06-01 -prefix sub-2 example.yaml

GANTT chart


Parameter -scale

since v0.8.1

TaskFalcon will try to find the best scale for your diagrams to be displayed on a standard monitor.

You can use the parameter -scale <DAY|WEEK|MONTH|YEAR> if you like to see more/less details.

Example

falcon -today 2020-06-01 -scale day example.yaml

GANTT chart

falcon -today 2020-06-01 -scale week example.yaml

GANTT chart

falcon -today 2020-06-01 -scale month example.yaml

GANTT chart


Parameter -show-closed-tasks

since v0.8.8

By default, TaskFalcon hides tasks that have been completed before today. With -show-closed-tasks you can force TaskFalcon to show those tasks.

Example

falcon -today 2020-06-18 -show-closed-tasks example.yaml

GANTT chart


Parameters -show-ends, -show-efforts and -show-effortsleft

By default TaskFalcon will render two columns with the name of a task and the calculated start date.

With -show-ends, you can show the end date of a task or group in a separate column. since v0.8.1

With -show-efforts, you can show the total amount of efforts required for a task. since v0.8.1

With -show-effortsleft, you can show the remaining efforts required to complete the task for the current date. since v0.9.4
The current date can be changed with -today YYYY-MM-DD.

Example

falcon -today 2020-06-18 -show-ends -show-efforts -show-effortsleft example.yaml

GANTT chart


Parameter -show-ids

since v0.8.1

In a complex project with hundreds of tasks, it can be sometimes difficult to find the ID of a task if you want to set a filter or create a task update. With the parameter -show-ids, TaskFalcon will use the ID of a task instead of the name in the diagram.

Example

falcon -today 2020-06-18 -show-ids example.yaml

GANTT chart


Parameters -start and -end

since v0.9.7

With the parameters -start and -end you can explicitly set the time range of the output diagrams.

You can use the format YYYY-MM-DD to set an absolute date:

falcon -start 2020-06-01 -end 2020-08-20 example.yaml

Or you can use a time range +/-<duration> relative to the current date (which can also be set with -today YYYY-MM-DD):

falcon -start -1w -end +4w example.yaml

Example

falcon -today 2020-06-15 -start -1w -end +1w example.yaml

GANTT chart


Parameter -sub-projects

since v0.8.7

Instead of rendering one diagram, which includes all imported sub projects, with this parameter TaskFalcon will generate one set of output diagrams for each imported project. This is useful if you need a combined resource planning across multiple projects but you want to visualise the tasks for each project individually.

Example

falcon -today 2020-06-01 -sub-projects example.yaml

GANTT chart

GANTT chart


Parameter -today

since v0.9.4

TaskFalcon uses the current date to show a vertical bar in the diagrams for the current day. By using -today you can change this to a specific date, using the format YYYY-MM-DD.

falcon -today 2020-06-15 example.yaml

Example

falcon -today 2020-06-15 example.yaml

GANTT chart


YAML files used for the examples on this page

Those are the project files, which were used for the examples on this page.

# File: example.yaml
project:
  name: Command-Line Examples
  start: 2020-06-01

imports:
  - resources.yaml
  - sub-1.yaml
  - sub-2.yaml
# File: sub-1.yaml
project:
  name: Sub-Project 1
  start: 2020-06-01

imports:
  - resources.yaml

tasks:
  - task: T1
    name: Task 1
    efforts: 10d
    assign: r1

  - task: T2
    name: Task 2
    length: 5d
    depends: T1

  - milestone: M1
    name: Finished
    depends: T1, T2
# File: sub-2.yaml
project:
  name: Sub-Project 2
  start: 2020-06-08

imports:
  - resources.yaml

tasks:
  - task: T1
    name: Task 1
    efforts: 5d
    assign: r1

  - task: T2
    name: Task 2
    efforts: 5d
    assign: r2

  - task: T3
    name: Task 2
    efforts: 15d
    assign: r1, r2

  - milestone: M1
    name: Finished
    depends: T1, T2, T3
# File: resources.yaml
resources:
  - resource: r1
    name: Worker 1

  - resource: r2
    name: Worker 2