Observe Command Line Interface Tool Overview

The Observe Command Line Interface (CLI) Tool allows you to interact with an Observe instance from the command line using the Observe API without requiring cURL at the command prompt. Observe provides a cloud-based observability platform that models machine data to help you debug issues with software and businesses fast.

Installing the Observe CLI Tool


You must install Go version 1.19.8, an open-source programming language supported by Google.

If you have Go installed, use the following command to install the Observe CLI tool:

go install https://github.com/observeinc/observe

Depending on how you installed Go and your environment, the binary appears in your go/bin directory.

You can find documentation for the Observe API here.


Download pre-built binaries for popular operating systems at Observe Releases. Put the binary somewhere in your go PATH.

Observe CLI Tool Quick Start


  • Observe Customer ID - your 12-digit customer ID for your Observe instance, for example, 123456789012

  • Observe instance URL - the hostname of your Observe instance, such as observeinc.com

  • Email address and password - the email address and password used to log into your Observe instance

Once you gather your prerequisites, run the following command:

$ observe --customerid 123456789012 --cluster observeinc.com login [email protected] --read-password --save
Password for 123456789012.observeinc.com: "[email protected]": 
login: saved authtoken to section "default" in config file "/home/myname/.config/observe.yaml"

Then, test your access using the following command:

$ observe query -q 'pick_col timestamp, log | limit 10' -i 'Default.kubernetes/Container Logs'
| timestamp           | log                                                       |
| 1679497866772157872 | E0420 16:20:00.123456 1 package/file.go:123] Hello World! |

The login command saves the generated Authentication Token in a local profile to reuse when you execute other commands. If you don’t want to save your Authentication Token in the profile, you can specify --authtoken on the command line, and not use the command, --save when logging into the instance.

If you use an SSO SAML integration such as Okta, Azure AD, Google, or PingOne, then see the section about the login command for how to generate credentials.

The name of the dataset input for your query may vary based on the installed or built datasets in your workspace, as well as the name of your workspace. Explore the Datasets page on your Observe instance to find more datasets. You can also use a dataset ID directly, such as 41007104, to specify the dataset to read. To specify more than one dataset to use for joins and unions, see the Query command section.

Configuring the CLI Command

Observe uses the following format for CLI commands:

observe [config-options] "command" [command-options]

The CLI uses config-options to specify general options such as the tenant and user for your interactions and where to read and write data.

The parameter, command, selects the major operating mode such as query or login. The parameter, command-options, specifies the specific action for the selected command.

Commands require three parameters to interact with the Observe service:

  • Customer ID - the numeric identifier of your customer account used in the URL, such as https://123456789012.observeinc.com/.

  • Observe instance URL - the hostname of your Observe instance such as observeinc.com.

  • Authentication token - your credentials that identify you and your privileges on the Observe instance. Similar to a password, you should store this token securely.

Specify the Customer ID using the parameter --customerid.

Specify the Observe instance using the parameter --cluster.

Specify the Authentication token using the parameter --authtoken.

You can also create a profile, such as a default profile, in the Configuration file and select the shape using the parameter, --profile.


The command, config-options, has different parameters than the command-options command. You may not specify any config-options after a command, and command-options may not be specified before the command.

Configuring Profile Files

The file, ~/.config/observe.yaml, can store your commonly used configuration options, such as the customer ID and the cluster URL. If you want, you can include the authentication token if handled securely. The YAML file contains a list of profiles, and you can choose a profile using the --profile command line option. If you do not specify a specific profile, Observe uses the default profile. You can specify another file for this using the parameter, --config, or the environment variable OBSERVE_CONFIG.

The name of each option within the profile matches the name of the corresponding config-option. For example,

    customerid: "123456789012"
    cluster: "observeinc.com"
    customerid: "234567890123"
    cluster: "observe-testing.com"
    timestamp: true
    workspace: Testing

With this profile configuration, you can use the default profile using the observe command ... and the testing profile using the observe --profile=testing command ....

If you don’t specify a profile on the command line but you set the Observe_Profile environment profile, then Observe uses that profile.

Output and Printing of the CLI Tool

The CLI options in the table can provide more information about your Observe instance.




Displays the current configuration used from the command line, profile, or environment. Or, it can be a combination of all three options.


Prints more verbose output about the current state, which may be helpful when automating actions and debugging failed actions. The output prints to the standard error output stream.


Prints less verbose output about an ongoing activity which may be preferred.


Timestamps each progress, debug, or error message, which may be useful when you use this tool to automate tasks but harder to read when using the tool interactively.

Observe sends error, progress, and debug information to the standard error stream. The CLI sends actual data output from a command to the standard output stream or to a file specified using the --output=filename. Data output redirection is a global configuration option and not an option for a specific command.