Pants commands are known as goals. A goal is a request to Pants to provide some data.

Examples of goals include test , which is a request to provide test results, and lint, which is a request to find logical and formatting errors in code.

To satisfy a goal, Pants will use cached data whenever possible, and perform work to compute the data (and cache it) when necessary. Pants will perform work concurrently as much as possible, using all the local cores, and/or any remote build executors, it has access to.

Which goals are available?

Pants is an extensible system, so the exact goals that are available depend upon which backends are enabled.

To see the current list of goals, run:

$ <<pantscmd>> goals

For example, if you have the default backends installed, you should see:

$ <<pantscmd>> goals
Goals
-----

Use `./pants help $goal` to get help for a particular goal.


cloc          Count lines of code.

dependees     List all targets that depend on any of the input targets.

dependencies  List the dependencies of the input targets.

filedeps      List all source and BUILD files a target depends on.

list          Lists all targets matching the file or target arguments.

roots         List the repo's registered source roots.

target-types  List all the registered target types, including custom plugin
              types.

validate      Validate sources against regexes.

Running goals

Let's try running a goal:

$ <<pantscmd>> target-types
Target types
------------

Use `./pants target-types --details=$target_type` to get detailed information
for a particular target type.


files                       A collection of loose files which do not have their
                            source roots stripped.

resources                   A collection of loose files.

target                      A generic target with no specific target type.

Goal arguments

Some simple goals, such as the target-types goal, take no arguments. But most goals require some arguments to work on.

For example, to run the cloc goal, which counts lines of code in your repo, you need to provide a set of files to run on:

$ <<pantscmd>> cloc '**'
github.com/AlDanial/cloc v 1.80  T=0.02 s (747.6 files/s, 24039.4 lines/s)
--------------------------------------------------------------------------------
Language                      files          blank        comment           code
--------------------------------------------------------------------------------
Bourne Again Shell                2             39             36            164
Python                            9             44             18             76
TOML                              1              8             10             21
Markdown                          1              0              0              2
--------------------------------------------------------------------------------
SUM:                             13             91             64            263
--------------------------------------------------------------------------------

📘
Quoting file patterns
Note the single-quotes around the file pattern '**'. This is so that your shell doesn't attempt to expand the pattern, but instead passes it unaltered to Pants.

File arguments vs. target arguments

Goal arguments can be of one of two types:

File arguments: file paths, or path globs, of files to act on.
Target arguments: addresses, or address globs, of targets to act on.

Any goal can take either type of argument:

If a target argument is given, the goal acts on all the files in the matching targets.
If a file argument is given Pants will map the file back to its containing target to read any necessary metadata.

So, for the most part, you can just use file arguments and not worry about targets!

📘
Tip: advanced target selection, such as running over changed files
See Advanced target selection for various alternative techniques to specify which files/targets to run on.

Goal options

Many goals also have options to change how they behave.

To see if a goal has any options, run <<pantscmd>> help $goal. See Command Line Help for more information.

For example:

$ <<pantscmd>> help target-types
`target-types` options
----------------------

List all the registered target types, including custom plugin types.

  --target-types-details=<target_type>
      default: None
      List all of the target type's registered fields.

  --target-types-output-file=<path>
      default: None
      Output to this file.  If unspecified, outputs to stdout.

  --target-types-sep=<separator>
      default: \n
      String to use to separate lines in line-oriented output.

You can then use the option by prefixing it with the goal name:

$ <<pantscmd>> --target-types-details=files target-types
files
-----

A collection of loose files which do not have their source roots stripped.

The sources of a `files` target can be accessed via language-specific APIs, such as Python's
`open()`. Unlike the similar `resources()` target type, Pants will not strip the source root of
`files()`, meaning that `src/python/project/f1.txt` will not be stripped down to
`project/f1.txt`.

Valid fields:

    dependencies
        type: Iterable[str] | None, default: None
        Addresses to other targets that this target depends on, e.g.
        `['src/python/project:lib']`.

    description
        type: str | None, default: None
        A human-readable description of the target. Use `./pants list --documented ::`
        to see all targets with descriptions.

    sources
        type: Iterable[str], required
        A list of files and globs that belong to this target. Paths are relative to the
        BUILD file's directory. You can ignore files/globs by prefixing them with `!`.
        Example: `sources=['example.py', 'test_*.py', '!test_ignore.py']`.

    tags
        type: Iterable[str] | None, default: None
        Arbitrary strings that you can use to describe a target. For example, you may
        tag some test targets with 'integration_test' so that you could run `./pants
        --tags='integration_test' test ::` to only run on targets with that tag.

As a shorthand, if you put the option after the goal, you can leave off the goal name in the flag:

$ <<pantscmd>> target-types --details=files