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.

  -all-updates
        Also applies updates that lie after 'today'
  -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-accounts-xlsx
        Exports a summary over all resources, tasks and accounts
  -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-click-map
        Exports a click map for each chart for integration with external tools
  -export-csv
        Export results to CSV file
  -export-json
        Export results to JSON 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-done
        Show percent value of completed efforts
  -show-efforts
        Shows efforts in an additional column
  -show-effortsleft
        Shows remaining task efforts for today in an additional column
  -show-effortsspent
        Shows efforts that already have been spent on a task by beginning of "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
  -tags string
        Provides a comma separated list of tag filters for rendering. Use +/- prefix to include/exclude tags. e.g. "+tag1,-tag2"
  -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.20. ©2020-2022 Marc Müller. All rights reserved.

Parameter -all-updates

Usually TaskFalcon will schedule all updates between project start and the parameter today (which is the current day unless set to a different value explicitly). Sometimes it might be useful to apply all updates even if they lie in the future. This command line option tells TaskFalcon to apply all updates independent of the current day or the parameter --today (see parameter --today).

Parameters -export-charts and -no-charts

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:

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

3. resources:
   Renders a resource utilisation chart:

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

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

Parameters -export-csv, -export-json, -export-xlsx

Theese parameters will export the scheduled plan to various output formats for further processing.

• -export-csv:
  Exports to a text based CSV (comma separated value) file with one task per row
• -export-json:
  Exports to a text based JSON format with tasks, projects and resource information
• -export-xlsx:
  Exports to a Microsoft Excel file with one task per row

Parameter -export-resource-slips

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

Parameter -no-updates

This parameter will force TaskFalcon to ignore all updates. The scheduler will only consider tasks and resources (including imported files).

Parameter -prefix

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

Parameter -scale

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

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

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

Parameter -show-closed-tasks

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

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

By default TaskFalcon will render two text 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-effortsspent, you can show the total amount of efforts already spent on a task until the current date. since v0.9.18

With -show-effortsleft, you can show the remaining efforts required to complete the task for the current date. since v0.9.4

With -show-done, you can show the relative progress of completenes of a task or group at the current date. since v0.9.13

The current date can be changed with -today YYYY-MM-DD. The shown efforts do not include buffers but only the estimated efforts.

Example

falcon -today 2020-06-18 -show-ends -show-efforts -show-effortsleft -show-effortsspent -show-done -show-closed-tasks example.yaml

Parameter -show-ids

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

Parameters -start and -end

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

Parameter -sub-projects

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

Parameter -tags

With tags you can customise the tasks that will be displayed in the exported diagrams or other formats. Tags that you assign to a task do not influence scheduling. When using the parameter -tags you can give it a comma separated list of tags you want to show or prevent from showing up in the output.

In the task definition, the tags are just a comma separated list of arbitrary names. In the command line, the listed tags can be prefixed with + to include or - to exclude a tag. If neither + nor - are provided, TaskFalcon will default to include a tag.

If multiple tags are given via command line, each task will be checked against all filters. The last filter to match the task will decide whether the task is shown.

If you only use excluding tags, TaskFalcon will show all tasks except for the excluded tasks. If you only use including tags or a combination of including/excluding tags, TaskFalcon will only show the tasks that are explicitly included in the tags.

Examples

Given this example file:

...
tasks:
  - task: T1
    length: 1d
    tags: a

  - task: T2
    length: 1d
    tags: b

  - task: T3
    length: 1d
    tags: a,b
...

Command line examples with explanation:

• falcon -tags a tags.yaml
  This will show tasks T1 and T3, since they both include tag a
• falcon -tags -b tags.yaml
  This will show task T1, since the other tasks are both tagged with tag b, which is excluded here
• falcon -tags a,-b tags.yaml
  This will show all tasks with tag a, but are not tagged with b. In this case you would see T1
• falcon -tags -a,b tags.yaml
  This will show all tasks with tag b, in this case T2 and T3. Since you are using a combination of + and - filters, it will only show tasks that are explicitly included.

Parameter -today

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

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 3
    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