Repository navigation
List experiment #2091
Description
Context
This is a proposal for a new API for the --list flag. It aims to unify the API for outputting tasks in a more consistent and intuitive way.
Obviously, we cannot break the API for the existing --list flag in v3, so I am proposing that the new API go behind an experiment (i.e. TASK_X_LIST). This will allow us to iterate and gather feedback on the design without worrying about breaking anything for existing users. The flag should come with a warning to users that it does not have a backward-compatible guarantee and should not be relied upon for scripts/CI. If the experiment is successful, then we could replace the existing --list and --list-all flags in a new major version release.
We may also want to consider the naming of the flag itself. In this proposal I have continued to call the flag --list, but in theory this flag could be used to format/display all sorts of things (tasks, taskfiles, DAGs, Profiling Reports etc). Maybe a more generic name would be suitable. Some ideas below:
--list--query- ???
This would also allow us to release the functionality in v3 since the change would not be breaking.
Design
This proposal has 3 main aims:
- Consolidate the output of tasks into a single
--listflag.- Any other flags related to the output should be implemented as "subflags" that supplement the
--listflag.
- Any other flags related to the output should be implemented as "subflags" that supplement the
- Make the design more intuitive and consistent with other well-known CLIs.
- Tidy up the code responsible for output and decouple it from the executor. This make it easier to:
- Add new filters and formats
- Write functional unit tests.
The following subsections describe the proposed API design in more detail:
Tags
tags is a new field that can be added to a task. It allows the user to attach some arbitrary metadata to a task that can then be used later for filtering and grouping. Multiple tags can be specified per task:
version: 3
tasks:
foo:
desc: 'Task foo'
tags: [foo, bar]
bar:
desc: 'Task bar'
tags: [foo]Filtering (--filter)
Filtering allows the user to filter the list of tasks using task attributes. We can do this by supporting some basic wildcard functionality (or maybe regex?). The flag can be supplied multiple times to add more filters. These filters are applied in the order specified. ! can be prefixed to a filter to negate its effect (i.e. it becomes an exclusion). Initial supported filtering attributes are:
namedesctags
Example usage:
task --list --filter name=foo*- Only lists tasks that start with "foo".- "foo1" and "foo2" will be included.
task --list --filter name={foo,bar}*- Only lists tasks whose names start with "foo" or "bar".- "foo1" and "foo2" will be included.
- "bar1" and "bar2" will be included.
task --list --filter !desc=- Removes tasks with no description (matches the current--listbehavior).- We could also allow for the shorthand
--filter !descfor this.
- We could also allow for the shorthand
task --list --filter tags=foo- Only lists tasks with the tag "foo".
Sorting (--sort/--sort-by)
Not much change here. This will work the same way as it does now.
Example usage:
task --list --sort nonetask --list --sort alphanumeric
However, we could add some additional sorting options:
task --list --sort alphanumeric --reverse- Reverse the sort ordertask --list --sort-by desc- Sort bydescinstead ofname
Formatting (--format)
Instead of having a separate flag for each format (we only have --json right now), we can use a single --format flag that accepts a string. This will allow us to add new formats in the future without having to add new flags.
Example usage:
task --list --format text- defaulttask --list --format json
In addition to this, we could create an API for raw string formatting using templating:
task --list --format '{{.Name}} - [{{.Aliases}}]'
Quiet (--quiet)
The current --silent flag is a bit of a misnomer. It doesn't silence the output, it just prints a non-formatted list. I propose that we follow the more conventional --quiet flag for this style of unformatted list. See the Docker CLI as a reference.
Example usage:
task --list --quiettask --list -q
There is no reason this does not also apply to other uses of silent too (e.g. in the Taskfile or when calling tasks using --silent).
.taskrc.yml
In addition to the above flags. Users might find it useful to change the defaults for their project. We could use our new configuration file to achieve this rather than complicating the Taskfile schema:
# .taskrc.yml
format: json
sort: none
sort-by: name
filters:
- name=foo*
- tags=barSpecifying a flag on the command line should override the .taskrc.yml settings.
Activity
task-bot commentedon Feb 26, 2025
This issue has been marked as an experiment proposal! 🧪 It will now enter a period of consultation during which we encourage the community to provide feedback on the proposed design. Please see the experiment workflow documentation for more information on how we release experiments.
iainvm commentedon Mar 12, 2025
Could this use a
--queryflag, so it doesn't conflict allowing people to keep--listbut test this experiment?pd93 commentedon Mar 12, 2025
True! There is no reason why this has to be a breaking change. We could continue to support
--listin v3 and deprecate its usage if we used another name. Something like--queryis a more generic name if we wanted to output other types of data too. I've updated the proposal with this suggestion.--list, have different colors per namespace / included Taskfile #1668--listand set a default filter #20896 remaining items
royw commentedon Nov 5, 2025
I've implement a utility, taskfile-help, that allows help: and search: tasks. Consider this my proof of concept vision of what I'd like to do with an extended --list or --query command.
Basically adds the equivalent of:
where:
NAMESPACE is:
STR is a zero or more strings to match in namespaces, groups, task names, or task descriptions.
REGEX is a python regular expression to match in namespaces, groups, task names, or task descriptions. The may be 0 or more --regex REGEX options.
Mixing STR and --regex REGEX is allowed.
There must be at least one STR or --regex REGEX.
The one work-around I used is a group comment instead of a group tag, which I hope the enhanced --list will have.
trevor-vaughan commentedon Apr 6, 2026
Hi folks. Been using Task recently and quite like it. I found the output format a bit rough and would like to propose the following updates. They've been working great for me and are all non-breaking but I wanted to get an idea of what you all would like before crashing the party.
trevor-vaughan/taskfile-task@d614390
--long/Lfor full descriptions as well as listing required variablesExample:
task -l --long:trevor-vaughan/taskfile-task@b8961aa
--tree/Twhich groups items by namespaceExample:
task -l --tree:trevor-vaughan/taskfile-task@79268ca
Example:
task -l lint:Example `task -l 'lint*':
feat(list): add --long flag and show required vars by default
feat(list): add --tree flag for namespace-grouped task display
feat(list): add filter pattern and match highlighting
feat(list): add --long flag and show required vars by default
feat(list): add --tree flag for namespace-grouped task display
feat(list): add filter pattern and match highlighting
feat(list): add --long flag and show required vars by default
feat(list): add --tree flag for namespace-grouped task display
feat(list): add filter pattern and match highlighting