> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Markers with CLI

> Add, update, and delete Honeycomb markers from the command line using curl or Honeymarker, Honeycomb's lightweight marker management CLI.

export const honeymarker = {
  "version": "2.12",
  "binary": {
    "sha256": "e74514a2baaf63a5828ff62ca2ca1aa86b3a4ab223ab6a7c53f969d7b55e37fb",
    "url": "https://honeycomb.io/download/honeymarker/linux/1.9"
  },
  "deb": {
    "sha256": "5aa10dd42f4f369c9463a8c8a361e46058339e6273055600ddad50e1bcdf2149",
    "url": "https://honeycomb.io/download/honeymarker/linux/honeymarker_1.9_amd64.deb"
  },
  "rpm": {
    "sha256": "0752ffd8633bb287b2f40af744eb24b4491025403d55367248bbe9320e5344e6",
    "url": "https://honeycomb.io/download/honeymarker/linux/honeymarker-1.9-1.x86_64.rpm"
  },
  "bin_name": "honeymarker"
};

To add markers via a command line tool, use either `curl` or [`honeymarker`](#honeymarker), a lightweight marker management tool that provides a CRUD command line interface.

<Note>
  Managing markers with a CLI requires a Configuration API Key, which must have the **Manage Markers** permission.
  Refer to [our API keys documentation](/configure/environments/manage-api-keys/#configuration-keys) for more details.
  Also, the dataset must already exist for a marker to be added successfully.
</Note>

### Add Markers (`add`)

For example:

<Tabs>
  <Tab title="honeymarker">
    ```shell theme={}
    honeymarker \
        -k YOUR_API_KEY \
        -d myservice \
        -t deploy \
        -m "build 192837" \
        add
    ```
  </Tab>

  <Tab title="curl">
    ```shell theme={}
    curl https://api.honeycomb.io/1/markers/myservice -X POST \
        -H "X-Honeycomb-Team: YOUR_API_KEY" \
        -d '{"message":"build 192837", "type":"deploy"}'
    ```

    <Note>
      To use our EU instance, post your data to `https://api.eu1.honeycomb.io/1/markers/myservice` instead.
    </Note>
  </Tab>
</Tabs>

#### honeymarker add

`honeymarker` has the following command line flags:

| Name       | Flag                              | Description                                                      | Required |
| ---------- | --------------------------------- | ---------------------------------------------------------------- | -------- |
| Start Time | `-s <arg>` / `--start_time=<arg>` | start time for the marker in unix time (seconds since the epoch) | No       |
| End Time   | `-e <arg>` / `--end_time=<arg>`   | end time for the marker in unix time (seconds since the epoch)   | No       |
| Message    | `-m <arg>` / `--msg=<arg>`        | message describing this specific marker                          | No       |
| URL        | `-u <arg>` / `--url=<arg>`        | URL associated with this marker                                  | No       |
| Type       | `-t <arg>` / `--type=<arg>`       | identifies marker type                                           | No       |

All parameters to add are optional.

If `start_time` is missing, the marker will be assigned the current time.

It is highly recommended that you fill in either message or type.
All markers of the same type will be shown with the same color in the UI.
The message will be visible above an individual marker.

If a URL is specified along with a message, the message will be shown as a link in the UI, and clicking it will take you to the URL.

### List Markers (`list`)

For example:

<Tabs>
  <Tab title="honeymarker">
    ```shell theme={}
    honeymarker \
        -k YOUR_API_KEY \
        -d myservice \
        list
    ```
  </Tab>

  <Tab title="curl">
    ```shell theme={}
    curl https://api.honeycomb.io/1/markers/myservice -X GET \
        -H "X-Honeycomb-Team: YOUR_API_KEY"
    ```

    <Note>
      To use our EU instance, get data from `https://api.honeycomb.io/1/markers/myservice` instead.
    </Note>
  </Tab>
</Tabs>

#### honeymarker list

`honeymarker` has the following command line flags:

| Name            | Flag          | Description                                                              | Required |
| --------------- | ------------- | ------------------------------------------------------------------------ | -------- |
| JSON            | `--json`      | Output the list as json instead of in tabular form                       | No       |
| Unix Timestamps | `--unix_time` | In table mode, format times as unit timestamps (seconds since the epoch) | No       |

### Update Markers (`update`)

For example:

<Tabs>
  <Tab title="honeymarker">
    ```shell theme={}
    honeymarker \
        -k YOUR_API_KEY \
        -d myservice \
        -i marker-id \
        -u "http://my.service.co/builds/192837" \
        update
    ```
  </Tab>

  <Tab title="curl">
    ```shell theme={}
    curl https://api.honeycomb.io/1/markers/myservice/marker-id -X PUT \
        -H "X-Honeycomb-Team: YOUR_API_KEY" \
        -d '{"url":"http://my.service.co/builds/192837"}'
    ```

    <Note>
      To use our EU instance, send data to `https://api.eu1.honeycomb.io/1/markers/myservice/marker-id` instead.
    </Note>
  </Tab>
</Tabs>

#### honeymarker update

`honeymarker` has the following command line flags:

| Name       | Flag                              | Description                                                      | Required |
| ---------- | --------------------------------- | ---------------------------------------------------------------- | -------- |
| Marker ID  | `-i <arg>` / `--id=<arg>`         | ID of the marker to update                                       | Yes      |
| Start Time | `-s <arg>` / `--start_time=<arg>` | start time for the marker in unix time (seconds since the epoch) | No       |
| End Time   | `-e <arg>` / `--end_time=<arg>`   | end time for the marker in unix time (seconds since the epoch)   | No       |
| Message    | `-m <arg>` / `--msg=<arg>`        | message describing this specific marker                          | No       |
| URL        | `-u <arg>` / `--url=<arg>`        | URL associated with this marker                                  | No       |
| Type       | `-t <arg>` / `--type=<arg>`       | identifies marker type                                           | No       |

The marker ID is available from the `list` command, and is also output to the console by the `add` command.

### Delete Markers (`rm`)

For example:

<Tabs>
  <Tab title="honeymarker">
    ```shell theme={}
    honeymarker \
        -k YOUR_API_KEY \
        -d myservice \
        -i marker-id \
        rm
    ```
  </Tab>

  <Tab title="curl">
    ```shell theme={}
    curl https://api.honeycomb.io/1/markers/myservice/marker-id -X DELETE \
        -H "X-Honeycomb-Team: YOUR_API_KEY"
    ```

    <Note>
      To use our EU instance, delete data from `https://api.eu1.honeycomb.io/1/markers/myservice/marker-id` instead.
    </Note>
  </Tab>
</Tabs>

#### honeymarker delete

`honeymarker` has the following command line flags:

| Name      | Flag                      | Description                | Required |
| --------- | ------------------------- | -------------------------- | -------- |
| Marker ID | `-i <arg>` / `--id=<arg>` | ID of the marker to delete | Yes      |

The marker ID is available from the `list` command, and is also output to the console by the `add` command.

## Honeymarker

`honeymarker` is a lightweight tool that provides a CRUD command line interface to manage your markers.

### Installation

Download and install the latest version of `honeymarker` by visiting the <a href={`https://github.com/honeycombio/honeymarker/releases/tag/v0.${honeymarker.version}`}>releases page for version {honeymarker.version} of honeymarker</a>, which contains binary packages for a variety of platforms.

The packages install `honeymarker` to `/usr/bin`.
The binary is called `honeymarker`, available if you need it in an unpackaged form or for ad-hoc use.

View [`honeymarker`'s source](https://github.com/honeycombio/honeymarker).

### Usage

Use the following command format for honeymarker:

```shell theme={}
honeymarker -k <YOUR_API_KEY> -d <dataset> COMMAND [command-specific flags]
```

where:

* `<YOUR_API_KEY>` is found on `<https://ui.honeycomb.io/account>`.
* `<dataset>` is the name of the dataset for which you want to create the marker.
* `COMMAND` is one of [available commands](#available-commands) listed below.

<Note>
  For Environment markers, use `__all__` for dataset name.
</Note>

### Available Commands

`honeymarker` has the following commands:

| Command                            | Description      |
| ---------------------------------- | ---------------- |
| [`add`](#add-markers-add)          | add a new marker |
| [`list`](#list-markers-list)       | list all markers |
| [`rm`](#delete-markers-rm)         | delete a marker  |
| [`update`](#update-markers-update) | update a marker  |

## OpenTelemetry Marker Exporter

The OpenTelemetry Collector's [Marker Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/honeycombmarkerexporter) allows you to send a [Honeycomb Marker](/configure/environments/manage-markers/) based on the shape of incoming telemetry.

In your OpenTelemetry Collector exporter configuration, you can specify a set of rules that will be evaluated against incoming telemetry.
When a condition is met, a marker is sent and appears in Honeycomb.
For example, whenever a Kubernetes Event contains a `reason` of `Backoff`, the configuration below sends a marker:

```yaml theme={}
exporters:
  honeycombmarker:
    api_key: YOUR-API-KEY-HERE
    markers:
      # Creates a new marker each time the exporter sees a Kubernetes event with a reason of Backoff
      - type: k8s-backoff-events
        rules:
          - log_conditions:
              - IsMap(body) and IsMap(body["object"]) and body["object"]["reason"] == "Backoff"
```