---
name: "riemann-client"
section: "1"
platform: "linux"
package: "riemann-c-client"
version: "1.10.4-4+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/riemann-client"
---

# riemann-client(1)

Riemann communication tool

## NAME

**riemann-client** - Riemann communication tool

## SYNOPSIS

**riemann-client** **query** \[*OPTIONS*...\] *QUERY* \[*HOST*\] \[*PORT*\]\
 **riemann-client** **send** \[*OPTIONS*...\] \[*HOST*\] \[*PORT*\]\
 **riemann-client** **--help**\|**-?**\
 **riemann-client** **--version**

## DESCRIPTION

**riemann-client** is a very simple tool to facilitate communication with a Riemann event stream processing server. It can be used both for sending events to one, and to query it too.

## OPTIONS

In both **query** and **send** mode, *HOST* and *PORT* default to *localhost* and *5555*, respectively.

### Query mode

In query mode, **riemann-client** takes one mandatory argument: the query itself. It must be a single argument, which will be sent to Riemann as-is, and the response dumped to the standard output, or, in case of an error, the error message will be written to the standard error.

See the Riemann documentation *http://riemann.io/concepts.html* for more information about the query syntax.

Apart from the mandatory argument, the **riemann-client** accepts the following options in query mode:

- **-j**, **--json**

  Print the result in JSON format, instead of the default, human-readable one.

- **-T**, **--tcp**

  Send the event via TCP (the default).

- **-G**, **--tls**

  Send the event via TLS.

- **-o**, **--option** *option*=*value*

  Set one client option to the given value.

  Available client options are:

  - **cafile**

    Path to the file containing trusted certificate authority certificates. Only used for TLS connections.

  - **certfile**

    Path to the file containing the public client certificate. Only used for TLS connections.

  - **keyfile**

    Path to the file containing the private client key. Only used for TLS connections.

  - **priorities**

    Priorities for the cipher suites to be used for the session.

### Submit mode

In submit mode, **riemann-client** accepts the following options:

- **-s**, **--state** *STATE*

  The state the event should describe, free-form text, optional.

- **-S**, **--service** *SERVICE*

  The service the event is coming from.

- **-h**, **--host** *HOST*

  The host the event originates from. Not to be confused with the optional *HOST* parameter of **riemann-client** itself, which sets where to send the events to.

- **-D**, **--description** *DESCRIPTION*

  The description of the event, optional.

- **-t**, **--tag** *TAG*

  This option can be used multiple times to add tags to the event.

- **-a**, **--attribute** *NAME*=*VALUE*

  This option can be used multiple times to add custom attributes to the event.

- **-i**, **--metric-sint64** *METRIC*

  Sets the metric for the event, using integer precision.

- **-d**, **--metric-d** *METRIC*

  Sets the metric of the event, using double precision.

- **-f**, **--metric-f** *METRIC*

  Sets the metric of the event, using floating point precision.

- **-L**, **--ttl** *TTL*

  An optional time-to-live of the event, in seconds (floating point number).

- **-T**, **--tcp**

  Send the event via TCP (the default).

- **-U**, **--udp**

  Send the event via UDP.

- **-G**, **--tls**

  Send the event via TLS.

- **-o**, **--option** *option*=*value*

  Set one client option to the given value.

  Available client options are:

  - **cafile**

    Path to the file containing trusted certificate authority certificates. Only used for TLS connections.

  - **certfile**

    Path to the file containing the public client certificate. Only used for TLS connections.

  - **keyfile**

    Path to the file containing the private client key. Only used for TLS connections.

  - **priorities**

    Priorities for the cipher suites to be used for the session.

- **-0**, **--stdin**

  Continuously read and send metrics and states from standard input. Uses all other fields specified on the command line. For each line on standard input, a new event will be sent to Riemann. If the input is a number, it will be used as a metric. If not, it will be used as the state. If it is a number, followed by a space and some string, then both metric and state will be set for the outgoing event.

## EXAMPLES

### Sending an event

```
$ riemann-client send --state ok \
                      --service "client-test" \
                      --host "my-host" \
                      --description "A message from the Manual" \
                      --tag tag-1 --tag tag-2 \
                      --attribute x-manual=best-friend \
                      --metric-sint64 1 \
                      --ttl 300.5 \
                      --tcp
```

### Sending metrics / state from standard input

```
$ echo "1.5 ok" |  \
  riemann-client send --service "client-test: stdin" \
                      --host "my-host" \
                      --description "A message from STDIN" \
                      --tag stdin \
                      --tcp \
                      --stdin
```

### Querying Riemann

```
$ riemann-client query 'host = "my-host"'
```

### Using TLS

```
$ riemann-client query 'host = "my-host"' \
                       --tls \
                       --option cafile=tests/data/cacert.pem \
                       --option certfile=tests/data/client.crt \
                       --option keyfile=tests/data/client.key \
                       --option priorities=NORMAL \
                       localhost 5554
```

## AUTHOR

Gergely Nagy *algernon@madhouse-project.org*