> For the complete documentation index, see [llms.txt](https://no0dles.gitbook.io/hammerkit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://no0dles.gitbook.io/hammerkit/labels.md).

# Labels

A label is a key value pair. They can be defined on tasks or build files.

Labeling your tasks will allow you to run multiple task groups or exclude specific tasks.

## Example use cases

The following use cases are just some examples to showcase some of the potential usage for labels.

### Separating tasks by area

Labels can be useful to separate tasks. For example if you share one build file for different parts of your application or in case of a bigger project/monorepo. Add a `project` label to your tasks and be able to build projects independently with a single command `hammerkit -f project=a` or `hammerkit -f project=b`.

{% hint style="info" %}
Label filters are always given as `key=value`. A bare `-f project` (key only) is rejected. Use `-f` (`--filter`) to keep only matching tasks and `-e` (`--exclude`) to drop them; both can be repeated or take multiple values.
{% endhint %}

```yaml
tasks:
  build-a:
    deps: [install-a]
    labels:
      project: a
    cmds:
      - tsc -b ./project/a
  
  test-a:
    deps: [install-a]
    labels:
      project: a
    cmds:
      - jest

  build-b:
    deps: [install-b]
    labels:
      project: b
    cmds:
      - tsc -b ./project/b
```

### Separate by platform

Labels can be used to separate your tasks in your CI. In a CI environment where there are two runners, one that runs macOS and the other linux. With the goal to use the macOS host only for the ios related code and the rest should run on linux. Add a `platform=ios` label to the task that require macOS and configure your ci to run `hammerkit -f platform=ios` on the mac host and `hammerkit -e platform=ios` on the linux host.

If there are tasks dependencies between the platform tasks, take a look at [store / restore](/hammerkit/cli/store-restore.md). These can be used to store and restore generated outputs from tasks, work as well with the label arguments `hammerkit store cache -e platform=ios` and help to move data/cache between hosts.

```yaml
tasks:
  build-ios:
    labels:
      platform: ios
    cmds:
      - xcodebuild ...
  
  build-api:
    image: node
    cmds:
      - tsc -b

  publish-testflight:
    deps: [build-ios]
    labels:
      platform: ios
    cmds:
      - altool upload-app ...
```

### Group by purpose

Simplify your workflow by grouping task together. Run one command for multiple tasks that have no dependency otherwise. For example a `task` label for either developing or publishing. `hammerkit -f task=dev` will start your api server with the frontend development watch build. `hammerkit -f task=release` will upload your container image to docker hub and build and upload to the staging environment.

```yaml
tasks:
  frontend:
    labels:
      task: dev
    cmds:
      - ng serve

  api:
    labels:
      task: dev
    cmds:
      - dotnet run
  
  publish-s3:
    labels:
      task: release
    cmds:
      - ng build
      - aws s3 cp dist/frontend s3://staging-web
  
  publish-api:
    labels:
      task: release
    cmds:
      - docker build ...
      - docker push ... 
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://no0dles.gitbook.io/hammerkit/labels.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.