The Grepr CLI

The Grepr command-line interface (CLI) allows you to manage and interact with resources on the Grepr platform from your terminal. You can also use the CLI in your scripts or clients to automate tasks. This page includes instructions for installing, configuring, authenticating, and running commands with the CLI. This page also includes examples showing how to use the CLI commands. Using the CLI, you can:

Create, update, and delete Grepr jobs such as pipelines, as well as list your jobs and retrieve job details and status.
Run queries against your data in the Grepr data lake.
Manage resources such as integrations and datasets.

Features of the Grepr CLI include:

Secure authentication with OAuth 2.0, including the automatic refresh and storage of tokens.
Management of multiple named configuration profiles, such as different profiles for development, staging, and production environments.
Real-time streaming of job results in a standard, structured format.
A choice of output format for results, including enhanced tables, CSV, pretty-printed JSON, raw, and, when you need to save space, a compact single-line JSON without indentation format.
Save results directly to files with the --output option.

The Grepr CLI uses the Grepr REST APIs to provide a convenient command-line interface for common operations. For more advanced programmatic access, you can use the APIs directly. See Automate Grepr processing with the Grepr REST APIs.

Requirements

Installing the Grepr CLI requires Node.js version 20 or later.

Install the Grepr CLI

To install the CLI, Grepr recommends installing the CLI globally from the npm registry. A global install lets you run the CLI from any terminal you open.

To install the CLI from the npm registry, you can use npm, yarn, or pnpm:


# Install globally with npm
npm install -g @grepr/cli


# Install globally with yarn
yarn global add @grepr/cli


# Install globally with pnpm
pnpm add -g @grepr/cli

After installing, you can run the CLI from any terminal prompt:


grepr --help

You can also run the CLI without installing by using npx:


# Run directly from npm registry
npx @grepr/cli --help

Configure the Grepr CLI

You can configure multiple named CLI configurations, allowing you to easily switch between different Grepr environments, such as development, staging, or production. Each configuration includes settings such as your organization name, API base URL, and values required for authentication. To use a named configuration, you specify the configuration name with the --conf option when running CLI commands. You can also set a default configuration to use when no --conf option is provided.

The following examples show how to create a configuration named dev and a configuration named prod, setting prod as the default configuration:


grepr --org-name myorgdev config:save dev
grepr --org-name myorgprod config:save prod --default

The CLI configurations you create are stored in the ~/.grepr/cli-config.json file with the following structure:


{
  "dev": {
    "orgName": "myorgdev",
    "authBaseUrl": "https://grepr-prod.us.auth0.com",
    "authMethod": "oauth",
    "clientId": "E4zbTBJrwaAKS1Gz1j1Ur53CJunZPlYv",
    "authCache": true,
    "browser": true,
    "apiBaseUrl": "https://myorgdev.app.grepr.ai/api"
  },
  "prod": {
    "orgName": "myorgprod",
    "authBaseUrl": "https://grepr-prod.us.auth0.com",
    "authMethod": "oauth",
    "clientId": "E4zbTBJrwaAKS1Gz1j1Ur53CJunZPlYv",
    "authCache": true,
    "browser": true,
    "apiBaseUrl": "https://myorgprod.app.grepr.ai/api"
  },
  "_default": "prod"
}

To use a specific configuration, include the --conf option with the configuration name in your CLI commands:


grepr --conf dev job:create templates/default-job.json

To use a default configuration, omit the --conf option when you run CLI commands:


grepr job:create templates/default-job.json

Authenticate to the Grepr CLI

The Grepr CLI authenticates using the login credentials for your Grepr organization. When you run your first CLI command or if your authentication token has expired, you’re redirected to a login form to sign in. After signing in with your Grepr credentials, you can return to the command line and wait for your command to complete.

Grepr jobs, pipelines, and queries

All processing in Grepr is done by Grepr jobs. The Grepr platform supports different job types, including Grepr pipelines, queries, and batch jobs. Pipelines are used for continuous data processing, such as processing logs before forwarding them to your observability vendor. Queries are used for ad-hoc retrieval of data from the Grepr data lake. While a pipeline is a streaming job that continuously processes data arriving from sources, a batch job receives a bounded set of data, processes that data, and then completes. The Grepr CLI includes two commands to access jobs:

The job command to create and manage Grepr jobs, including pipelines.
The query command to run ad-hoc queries against the Grepr data lake.

Examples of both commands are included below.

To learn more about Grepr jobs, see The Grepr processing and data models.

CLI command reference

CLI global options

The following options are available when you run any CLI command:


--conf <name>            Specify a saved configuration to use for this command.
--org-name <name>        Your organization name. This argument is required if you are not using a saved configuration.
--api-base-url <url>     API server base URL. The default is https://<orgName>.app.grepr.ai/api.
--auth-base-url <url>    Identity provider base URL. The default is https://grepr-prod.us.auth0.com.
--client-id <id>         OAuth 2.0 Client ID. The default is the web client ID.
--timezone <tz>          Timezone for timestamp formatting. The default is the system timezone.
-o, --output <file>      Output results to a file instead of stdout.
-d, --debug              Enable debug output.
-q, --quiet              Suppress non-essential output.

CLI command help

To display the help for a specific command, use the --help option with the command:


grepr <command> --help

For example:


grepr job:create --help
 
Usage: grepr job:create [options] <job-file>
 
Create a new job from file
 
Options:
  -f, --format <format>      Output format (table, csv, pretty, raw, compact) (default: "table")
  -s, --sort <column:order>  Sort table by column (e.g., "eventTimestamp:asc") (default: "eventTimestamp:asc")
  --max-depth <number>       Maximum object nesting depth for table columns (default: 1)
  --max-lines <number>       Maximum lines per table cell (default: 4)
  --no-color                 Disable colored output
  --no-timestamps            Hide timestamps
  --no-job-state             Hide job state messages
  -h, --help                 display help for command

Output formats

By default, the Grepr CLI outputs results in a formatted table, but you can choose other output formats with the --format option. The following output formats are supported:

Table format (default)

Displays results in a formatted table with:

Column wrapping (80 characters max).
Pretty-printed JSON in cells.
Configurable sorting.
Proper alignment.


+----------+------------------------+------------------+
| id       | eventTimestamp         | message          |
+----------+------------------------+------------------+
| abc123   | 10/19/2025, 6:00:00 PM | Error occurred   |
| def456   | 10/19/2025, 6:01:00 PM | Request          |
|          |                        | completed        |
+----------+------------------------+------------------+

Pretty format

Syntax-highlighted and correctly indented JSON:


{
  "id": "abc123",
  "eventTimestamp": "2025-10-19T18:00:00Z",
  "tags": {
    "service": "web-api",
    "environment": "prod"
  }
}

Raw format

Single line JSON, no syntax highlighting:


{"id":"abc123","eventTimestamp":"2025-10-19T18:00:00Z"}
{"id":"def456","eventTimestamp":"2025-10-19T18:01:00Z"}

CSV format

Comma-separated values with proper escaping:


id,eventTimestamp,message,tags
abc123,"10/19/2025, 6:00:00 PM","Error occurred","{""service"":[""web-api""]}"
def456,"10/19/2025, 6:01:00 PM","Request completed","{""service"":[""web-api""]}"

The CSV format is useful for data analysis tasks, importing events into spreadsheets, and data pipelines. Complex JSON data is transformed by properly escaping nested objects and arrays.

Compact format

Single-line JSON without indentation:


{"id":"abc123","eventTimestamp":"2025-10-19T18:00:00Z","message":"Error"}

Supported commands

The Grepr CLI includes commands to:

Configure CLI settings and preferences: config:save, config:delete, config:list, config:show, config:default.
Create and manage Grepr jobs: job:create, job:list, job:get, job:update, job:delete.
Apply transformations to a job configuration to create a new configuration for testing: job:to-test.
Run queries against data in the Grepr data lake: query.
Manage vendor and storage integrations: integration:list, integration:get.
Manage datasets for log storage and querying: dataset:create, dataset:list, dataset:get, dataset:update, dataset:delete.
Search and retrieve Grepr documentation: docs:search, docs:get.
Test Grok rules: grok:parse.

The following sections contain examples demonstrating how to use these commands. Most of these examples assume you have already saved a default configuration. If you haven’t saved a default configuration, include the --conf option to specify a saved configuration when you run CLI commands. To learn how to create a default configuration, see Configure the Grepr CLI.

Examples: Configure the CLI


# Save a configuration named "dev" and set it as the default
grepr config:save dev --org-name myorgdev --default


# List saved configurations
grepr config:list


# Show the settings for the saved "dev" configuration
grepr config:show dev


# Delete the saved "dev" configuration
grepr config:delete dev


# Set "prod" as the default configuration
grepr config:default prod

Examples: Integration commands

List integrations


# List information for all integrations, including names, identifiers, type, and any jobs using the integration
grepr integration:list


# List information for all integrations and output the results as CSV records
grepr integration:list --format csv


# List information for all integrations and output the results as JSON
grepr integration:list --format pretty

Get an integration


# Get an integration by ID
grepr integration:get <integration-id>


# Get an integration and save it to a file
grepr integration:get <integration-id> -o datadog-integration.json

Replace <integration-id> with the unique identifier for the integration to retrieve. You can find the integration ID in the output of the integration:list command.

Examples: Dataset commands

List datasets

You can use the datasets alias instead of dataset:list with the dataset commands. For example, grepr datasets instead of grepr dataset:list.


# List all datasets
grepr dataset:list


# List all datasets and output the results in a table
grepr dataset:list --format table --sort "name:asc"


# List the results as raw JSON
grepr dataset:list --format raw

Get a dataset


# Get a dataset by ID
grepr dataset:get <dataset-id>


# Get a dataset and save it to a file
grepr dataset:get <dataset-id> -o app-logs-dataset.json

Replace <dataset-id> with the unique identifier for the dataset to retrieve. You can find the dataset ID in the output of the dataset:list command.

Create a dataset

To create a dataset, pass a file containing the dataset definition to the dataset:create command. Dataset definitions are JSON files that specify the required and optional fields for creating a new Grepr dataset. See the Payload example in the Create a new dataset API specification.


# Create a dataset from a file
grepr dataset:create /path/to/dataset-definition.json

Update a dataset


# Update a dataset using a dataset definition stored in a file
grepr dataset:update <dataset-id> /path/to/updated-dataset.json

Replace <dataset-id> with the unique identifier for the dataset to retrieve. You can find the dataset ID in the output of the dataset:list command.

Delete a dataset


# The delete dataset command deletes only the metadata associated with the dataset, leaving the data files in place.
grepr dataset:delete <dataset-id>

Examples: Run queries


# Run a query over a time range against a dataset specified by its identifier
grepr query \
  --dataset-id <dataset-id> \
  --start 2026-02-26T00:00:00Z \
  --end 2026-02-26T23:59:00Z \
  --query "service:web-api AND level:ERROR" \
  --limit 100


# Run a query over a time range against a dataset specified by its name and output the results as CSV records to a file
grepr query \
  --dataset-name "<dataset-name>" \
  --start 2026-02-26T00:00:00Z \
  --end 2026-02-26T23:59:00Z \
  --format csv \
  --output errors.csv \
  --query "level:ERROR" \
  --limit 100

In these examples, replace:

<dataset-id> with the unique identifier for the dataset to retrieve. You can find the dataset ID in the output of the dataset:list command.
<dataset-name> with the name of the dataset to query. You can find the dataset name in the output of the dataset:list command or in the Grepr Data Explorer UI.

To learn more about supported query syntaxes, see Query log data in the Grepr data lake.

Examples: Job commands

List jobs

You can use the jobs alias instead of job:list with the dataset commands. For example, grepr jobs instead of grepr job:list.


# List all jobs
grepr job:list


# List all running jobs
grepr job:list --state RUNNING


# List jobs from the last 24 hours
grepr job:list --since PT24H


# List a specific job by name
grepr job:list --name "error-detection-pipeline"


# List jobs and output as CSV
grepr job:list --format csv --sort "name:asc"


# List all versions of jobs
grepr job:list --all-versions


# List batch jobs only
grepr job:list --processing BATCH


# List jobs with resolved definitions
grepr job:list --resolved

Get a job


# Get a job by ID
grepr job:get <job-id>


# Get a job definition and save it to a file
grepr job:get <job-id> -o my-job.json

Create a job

To create a job with the Grepr CLI, you pass a file containing the job definition to the job:create command. Job definitions are JSON files that specify all job configuration values, including dependencies, required to create a new Grepr job.

To learn more about job definitions, including examples, see Create and manage jobs with the Grepr REST API.

The following fields are required when you create a job definition:

name: A name identifying the job.
execution:
- SYNCHRONOUS for a job that streams results in real-time to the CLI. The output format is set with the --format option.
- ASYNCHRONOUS for a job that runs in the background. You can monitor these jobs with the job:list and job:get commands.
processing: BATCH or STREAMING.
jobGraph: the data processing pipeline definition.

The CLI automatically manages the creation of either synchronous or asynchronous jobs based on the execution field.

When you run a query command or a job:create command, the CLI displays the status of the job in real-time. The following table describes the possible job status values:

Status	Description
`[CONNECTING]`	Establishing connection.
`[CONNECTED]`	Connection established.
`[RUNNING]`	The job is processing data.
`[FINISHED]`	The job completed successfully.
`[FAILED]`	The job failed.
`[CANCELLED]`	The job was cancelled.
`[TIMED_OUT]`	The job exceeded the time limit.
`[SCANNED_MAX]`	The job exceeded the data scan limit.


# Create a job from a definition contained in the input file
grepr job:create /path/to/job-definition.json


# Create a job and stream the output in table format
grepr job:create /path/to/sync-job.json --format table


# Create a job and format the output as syntax-highlighted and indented JSON.
grepr job:create /path/to/job-definition.json --format pretty

Update a job


# Update a job definition from the definition contained in the input file
grepr job:update <job-id> /path/to/updated-job.json


# Update a job definition with rollback enabled
grepr job:update <job-id> /path/to/updated-job.json --rollback-enabled

Delete a job


grepr job:delete <job-id>

Examples: Test Grok patterns against sample log events


# Test a simple Grok parsing rule
grepr grok:parse \
  --pattern "ParsingRule %{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{GREEDYDATA:message}" \
  --sample "2026-02-17T10:15:30.123Z ERROR Failed to connect to database"


# Test a Grok parsing rule that reads sample access log events, like the following sample, from a file:
# 172.16.45.123 - - [15/Jan/2025:14:32:15 +0000] "POST /api/v2/logs HTTP/1.1" 202 2
grepr grok:parse \
  --pattern "ParsingRule %{IP:client_ip} - - \\[%{HTTPDATE:timestamp}\\] \"%{WORD:method} %{URIPATHPARAM:request} HTTP/%{NUMBER:http_version}\" %{NUMBER:status_code} %{NUMBER:bytes}" \
  --samples-file access.log


# Test a Grok parsing rule that extracts the value of the `service` attribute from a sample log event
grepr grok:parse \
  --pattern "ParsingRule %{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{DATA:service} %{GREEDYDATA:message}" \
  --sample "2026-02-17T10:15:30.123Z WARN auth-service Rate limit exceeded for user" \
  --extract-attribute service


# Parse with helper rules
grepr grok:parse \
  --pattern "ParsingRule %{CUSTOM_TIMESTAMP:timestamp} %{SEVERITY:level} %{GREEDYDATA:message}" \
  --sample "17-Feb-2026 10:15:30 CRITICAL System overload detected" \
  --helper-rules "CUSTOM_TIMESTAMP %{MONTHDAY}-%{MONTH}-%{YEAR} %{TIME}" "SEVERITY (CRITICAL|ERROR|WARN|INFO|DEBUG)"

Examples: Documentation commands

Use the CLI documentation commands to perform semantic searches of the Grepr documentation and retrieve documentation content. The CLI commands allow you to find and read relevant information without leaving the terminal, and can be particularly useful for tasks like working with AI assistants or scripting workflows.

The results returned by a documentation search can include three types of content:

User documentation (doc://): Tutorials, guides, and integration instructions.
API operations (api://): REST endpoint documentation with parameters, request/response schemas, and examples.
Data schemas (schema://): Complete schema definitions for job configurations and API payloads.

For example, searching for “create grok parser” will return both the GrokParser schema definition and the API endpoint for validating Grok rules. This makes it easy to find the exact structure needed for job configurations or API requests.

The typical workflow combines both commands:

Search to find relevant documentation: grepr docs:search "topic" -f compact
Get the full content using the URI from results: grepr docs:get "doc://path/to/file.mdx"

Search Documentation


# Basic search
grepr docs:search "how to create a pipeline"
grepr docs:search "datadog integration"


# Search with limit
grepr docs:search "grok patterns" --limit 10


# Restrict search to the REST API
grepr docs:search "create job" --type api


# Restrict search to the user documentation
grepr docs:search "log reduction" --type doc


# Restrict search to data schemas
grepr docs:search "grok parser" --type schema


# Search and output as JSON for scripting
grepr docs:search "log reduction" -f json


# Output text without color highlighting
grepr docs:search "grok patterns" --no-color


# Change preview length from the default of 400 characters
grepr docs:search "flink configuration" -p 200

Get full documentation

After you find a relevant document with docs:search, you can retrieve the full content of the document with the docs:get command using the document URI from the search results. The document URI is a unique identifier for each document in the Grepr documentation.


# Get a full document using the URI returned by search
grepr docs:get "doc://tutorials/first-pipeline/page.mdx"


# Get a full document and pipe it to an AI assistant or other tools
grepr docs:get "doc://tutorials/first-pipeline/page.mdx" | claude


# Get documentation for an API request
grepr docs:get "api://api/Jobs/submitSyncJob"


# Get a schema definition
grepr docs:get "schema://GrokParser"

To save the retrieved documentation to a file, use a shell redirect operator (>). The --output option is not supported for the docs:get command.


# Save documentation locally
grepr docs:get "doc://integrations/datadog/page.mdx" > datadog-docs.md

Troubleshooting

Capture full logs with the `debug` option

If you experience issues when running CLI commands, such as network issues, you can use the --debug option to capture the full logging output:


# Enable debug mode for detailed logging
grepr --conf dev --debug job:create job.json

Authentication failures

If you experience an authentication issue, you can often resolve it by re-authenticating. To re-authenticate, remove any currently cached tokens so that the next command you run requires authentication:


# Clear cached tokens and re-authenticate
rm -rf ~/.grepr/auth/
grepr --conf dev integration:list

Frequently Asked Questions

What is the Grepr CLI?

The Grepr CLI is a command-line interface that allows you to manage jobs, run queries, and automate Grepr tasks. It supports OAuth 2.0 authentication, multiple configuration profiles, and various output formats.

How do I install the Grepr CLI?

Install globally from npm with: npm install -g @grepr/cli or yarn global add @grepr/cli. You can also run it directly with: npx @grepr/cli --help

What are the CLI requirements?

The Grepr CLI requires Node.js version 20 or above.

How do I authenticate with the CLI?

The CLI uses OAuth 2.0 and automatically redirects you to a login form on your first command. After you sign in with your Grepr credentials, tokens are cached locally and refreshed automatically.

How do I clear cached authentication tokens?

Run: rm -rf ~/.grepr/auth/ to remove cached tokens. The next CLI command will require you to re-authenticate.

What output formats does the CLI support?

The CLI supports table (default), pretty (JSON with colors), raw (newline-delimited JSON), CSV, and compact (single-line JSON) output formats.

How do I save a CLI configuration?

Use: grepr --org-name myorg config:save myconfig. Optionally add --default to set it as the default configuration for future commands.

Can I search Grepr documentation from the CLI?

Yes, use grepr docs:search "topic" to search Grepr documentation. Results include user docs, API operations, and data schemas. Retrieve full content with grepr docs:get "uri".

How do I run a query with the CLI?

Use: grepr query --dataset-name "dataset" --query "level:ERROR" --start "2024-01-01T00:00:00Z" --end "2024-01-02T00:00:00Z"

What CLI commands are available?

The CLI supports job management (job:create, job:list, job:get, job:update, job:delete), queries, integration management, dataset management, configuration commands, and documentation search/retrieval.