diff --git a/README.md b/README.md index 1e16c8c4..6187b0ed 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,6 @@ To connect to Seq in a docker container on the local machine use the machine's I Use Docker networks and volumes to make local files and other containers accessible to `seqcli` within its container. - ### Connecting without an API key If you're automating Seq setup, chances are you won't have an API key yet for `seqcli` to use. During the initial Seq server configuration, you can specify `firstRun.adminUsername` and `firstRun.adminPasswordHash` (or the equivalent environment variables `SEQ_FIRSTRUN_ADMINUSERNAME` and `SEQ_FIRSTRUN_ADMINPASSWORDHASH`) to set an initial username and password for the administrator account. You can use these to create an API key, and then use the API key token with the remaining `seqcli` commands. @@ -60,41 +59,72 @@ When connecting with an API key the allowed operations are determined by the [pe To determine the permission required for a command check the 'Permission demand' column of the [equivalent server API operation](https://docs.datalust.co/docs/server-http-api). For example, the command `apikey create` uses the [`POST api/apikeys` endpoint](https://docs.datalust.co/docs/server-http-api#apiapikeys), which requires the `Write` permission. -## Commands +## Usage -Usage: +All `seqcli` commands follow the same pattern: ``` seqcli [] ``` -Available commands: +### Command help + +The complete list of supported commands can be viewed by running: + +``` +seqcli help +``` + +To show usage information for a specific command, run `seqcli help `, for example: + +``` +seqcli help apikey create +``` + +This also works for command groups; to list all `apikey` sub-commands, run: + +``` +seqcli help apikey +``` + +## Available commands - `apikey` - [`apikey create`](#apikey-create) — Create an API key for automation or ingestion. - [`apikey list`](#apikey-list) — List available API keys. - [`apikey remove`](#apikey-remove) — Remove an API key from the server. + - [`apikey update`](#apikey-update) — Update an existing API key. - `app` - [`app define`](#app-define) — Generate an app definition for a .NET `[SeqApp]` plug-in. - [`app install`](#app-install) — Install an app package. - [`app list`](#app-list) — List installed app packages. - [`app run`](#app-run) — Host a .NET `[SeqApp]` plug-in. + - [`app uninstall`](#app-uninstall) — Uninstall an app package. - [`app update`](#app-update) — Update an installed app package. - `appinstance` - [`appinstance create`](#appinstance-create) — Create an instance of an installed app. - [`appinstance list`](#appinstance-list) — List instances of installed apps. - [`appinstance remove`](#appinstance-remove) — Remove an app instance from the server. + - [`appinstance update`](#appinstance-update) — Update an existing app instance. - [`bench`](#bench) — Measure query performance. - [`config`](#config) — View and set fields in the `SeqCli.json` file; run with no arguments to list all fields. - `dashboard` - [`dashboard list`](#dashboard-list) — List dashboards. - [`dashboard remove`](#dashboard-remove) — Remove a dashboard from the server. - [`dashboard render`](#dashboard-render) — Produce a CSV or JSON result set from a dashboard chart. +- `expressionindex` + - [`expressionindex create`](#expressionindex-create) — Create an expression index. + - [`expressionindex list`](#expressionindex-list) — List expression indexes. + - [`expressionindex remove`](#expressionindex-remove) — Remove an expression index from the server. - `feed` - [`feed create`](#feed-create) — Create a NuGet feed. - [`feed list`](#feed-list) — List NuGet feeds. - [`feed remove`](#feed-remove) — Remove a NuGet feed from the server. + - [`feed update`](#feed-update) — Update an existing NuGet feed. - [`help`](#help) — Show information about available commands. +- `index` + - [`index list`](#index-list) — List indexes. + - [`index suppress`](#index-suppress) — Suppress an index. - [`ingest`](#ingest) — Send log events from a file or `STDIN`. - [`license apply`](#license-apply) — Apply a license to the Seq server. - [`log`](#log) — Send a structured log event to the server. @@ -112,6 +142,7 @@ Available commands: - [`retention create`](#retention-create) — Create a retention policy. - [`retention list`](#retention-list) — List retention policies. - [`retention remove`](#retention-remove) — Remove a retention policy from the server. + - [`retention update`](#retention-update) — Update an existing retention policy. - `sample` - [`sample ingest`](#sample-ingest) — Log sample events into a Seq instance. - [`sample setup`](#sample-setup) — Configure a Seq instance with sample dashboards, signals, users, and so on. @@ -126,6 +157,7 @@ Available commands: - [`signal import`](#signal-import) — Import signals in newline-delimited JSON format. - [`signal list`](#signal-list) — List available signals. - [`signal remove`](#signal-remove) — Remove a signal from the server. + - [`signal update`](#signal-update) — Update an existing signal. - [`tail`](#tail) — Stream log events matching a filter. - `template` - [`template export`](#template-export) — Export entities into template files. @@ -134,11 +166,13 @@ Available commands: - [`user create`](#user-create) — Create a user. - [`user list`](#user-list) — List users. - [`user remove`](#user-remove) — Remove a user from the server. + - [`user update`](#user-update) — Update an existing user. - [`version`](#version) — Print the current executable version. - `workspace` - [`workspace create`](#workspace-create) — Create a workspace. - [`workspace list`](#workspace-list) — List available workspaces. - [`workspace remove`](#workspace-remove) — Remove a workspace from the server. + - [`workspace update`](#workspace-update) — Update an existing workspace. ### `apikey create` @@ -159,7 +193,7 @@ seqcli apikey create -t 'Test API Key' -p Environment=Test | `--minimum-level=VALUE` | The minimum event level/severity to accept; the default is to accept all events | | `--use-server-timestamps` | Discard client-supplied timestamps and use server clock values | | `--permissions=VALUE` | A comma-separated list of permissions to delegate to the API key; valid permissions are `Ingest` (default), `Read`, `Write`, `Project` and `System` | -| `--connect-username=VALUE` | A username to connect with, useful primarily when setting up the first API key | +| `--connect-username=VALUE` | A username to connect with, useful primarily when setting up the first API key; servers with an 'Individual' subscription only allow one simultaneous request with this option | | `--connect-password=VALUE` | When `connect-username` is specified, a corresponding password | | `--connect-password-stdin` | When `connect-username` is specified, read the corresponding password from `STDIN` | | `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | @@ -208,6 +242,24 @@ seqcli apikey remove -t 'Test API Key' | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | | `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +### `apikey update` + +Update an existing API key. + +Example: + +``` +seqcli apikey update --json '{...}' +``` + +| Option | Description | +| ------ | ----------- | +| `--json=VALUE` | The updated API key in JSON format; this can be produced using `seqcli apikey list --json` | +| `--json-stdin` | Read the updated API key as JSON from `STDIN` | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `app define` Generate an app definition for a .NET `[SeqApp]` plug-in. @@ -289,6 +341,24 @@ seqcli tail --json | seqcli app run -d "./bin/Debug/netstandard2.2" -p ToAddress | `--id=VALUE` | The app instance id, used only for app configuration; defaults to a placeholder id. | | `--read-env` | Read app configuration and settings from environment variables, as specified in https://docs.datalust.co/docs/seq-apps-in-other-languages; ignores all options except --directory and --type | +### `app uninstall` + +Uninstall an app package. + +Example: + +``` +seqcli app uninstall --package-id 'Seq.App.JsonArchive' +``` + +| Option | Description | +| ------ | ----------- | +| `--package-id=VALUE` | The package id of the app package to uninstall | +| `-i`, `--id=VALUE` | The id of a single app package to uninstall | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `app update` Update an installed app package. @@ -328,7 +398,7 @@ seqcli appinstance create -t 'Email Ops' --app hostedapp-314159 -p To=ops@exampl | `-t`, `--title=VALUE` | A title for the app instance | | `--app=VALUE` | The id of the installed app package to instantiate | | `-p`, `--property=NAME=VALUE` | Specify name/value settings for the app, e.g. `-p ToAddress=example@example.com -p Subject="Alert!"` | -| `--stream[=VALUE]` | Stream incoming events to this app instance as they're ingested; optionally accepts a signal expression limiting which events should be streamed | +| `--stream[=VALUE]` | Stream incoming events to this app instance as they're ingested; optionally accepts a signal expression limiting which events should be streamed, for example `signal-1,signal-2` | | `--overridable=VALUE` | Specify setting names that may be overridden by users when invoking the app | | `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | @@ -376,6 +446,24 @@ seqcli appinstance remove -t 'Email Ops' | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | | `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +### `appinstance update` + +Update an existing app instance. + +Example: + +``` +seqcli appinstance update --json '{...}' +``` + +| Option | Description | +| ------ | ----------- | +| `--json=VALUE` | The updated app instance in JSON format; this can be produced using `seqcli appinstance list --json` | +| `--json-stdin` | Read the updated app instance as JSON from `STDIN` | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `bench` Measure query performance. @@ -473,6 +561,63 @@ seqcli dashboard render -i dashboard-159 -c 'Response Time (ms)' --last 7d --by | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | | `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +### `expressionindex create` + +Create an expression index. + +Example: + +``` +seqcli expressionindex create --expression "ServerName" +``` + +| Option | Description | +| ------ | ----------- | +| `-e`, `--expression=VALUE` | The expression to index | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +| `--json` | Print output in newline-delimited JSON (the default is plain text) | +| `--no-color` | Don't colorize text output | +| `--force-color` | Force redirected output to have ANSI color (unless `--no-color` is also specified) | + +### `expressionindex list` + +List expression indexes. + +Example: + +``` +seqcli expressionindex list +``` + +| Option | Description | +| ------ | ----------- | +| `-i`, `--id=VALUE` | The id of a single expression index to list | +| `--json` | Print output in newline-delimited JSON (the default is plain text) | +| `--no-color` | Don't colorize text output | +| `--force-color` | Force redirected output to have ANSI color (unless `--no-color` is also specified) | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + +### `expressionindex remove` + +Remove an expression index from the server. + +Example: + +``` +seqcli expressionindex -i expressionindex-2529 +``` + +| Option | Description | +| ------ | ----------- | +| `-i`, `--id=VALUE` | The id of an expression index to remove | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `feed create` Create a NuGet feed. @@ -536,6 +681,24 @@ seqcli feed remove -n CI | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | | `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +### `feed update` + +Update an existing NuGet feed. + +Example: + +``` +seqcli feed update --json '{...}' +``` + +| Option | Description | +| ------ | ----------- | +| `--json=VALUE` | The updated NuGet feed in JSON format; this can be produced using `seqcli feed list --json` | +| `--json-stdin` | Read the updated NuGet feed as JSON from `STDIN` | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `help` Show information about available commands. @@ -550,6 +713,43 @@ seqcli help search | ------ | ----------- | | `-m`, `--markdown` | Generate markdown for use in documentation | +### `index list` + +List indexes. + +Example: + +``` +seqcli index list +``` + +| Option | Description | +| ------ | ----------- | +| `-i`, `--id=VALUE` | The id of a single index to list | +| `--json` | Print output in newline-delimited JSON (the default is plain text) | +| `--no-color` | Don't colorize text output | +| `--force-color` | Force redirected output to have ANSI color (unless `--no-color` is also specified) | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + +### `index suppress` + +Suppress an index. + +Example: + +``` +seqcli index suppress -i index-2191448f1d9b4f22bd32c6edef752748 +``` + +| Option | Description | +| ------ | ----------- | +| `-i`, `--id=VALUE` | The id of an index to suppress | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `ingest` Send log events from a file or `STDIN`. @@ -812,6 +1012,24 @@ seqcli retention remove -i retentionpolicy-17 | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | | `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +### `retention update` + +Update an existing retention policy. + +Example: + +``` +seqcli retention update --json '{...}' +``` + +| Option | Description | +| ------ | ----------- | +| `--json=VALUE` | The updated retention policy in JSON format; this can be produced using `seqcli retention list --json` | +| `--json-stdin` | Read the updated retention policy as JSON from `STDIN` | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `sample ingest` Log sample events into a Seq instance. @@ -998,6 +1216,24 @@ seqcli signal remove -t 'Test Signal' | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | | `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +### `signal update` + +Update an existing signal. + +Example: + +``` +seqcli signal update --json '{...}' +``` + +| Option | Description | +| ------ | ----------- | +| `--json=VALUE` | The updated signal in JSON format; this can be produced using `seqcli signal list --json` | +| `--json-stdin` | Read the updated signal as JSON from `STDIN` | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `tail` Stream log events matching a filter. @@ -1117,6 +1353,24 @@ seqcli user remove -n alice | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | | `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +### `user update` + +Update an existing user. + +Example: + +``` +seqcli user update --json '{...}' +``` + +| Option | Description | +| ------ | ----------- | +| `--json=VALUE` | The updated user in JSON format; this can be produced using `seqcli user list --json` | +| `--json-stdin` | Read the updated user as JSON from `STDIN` | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ### `version` Print the current executable version. @@ -1185,6 +1439,24 @@ seqcli workspace remove -t 'My Workspace' | `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | | `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | +### `workspace update` + +Update an existing workspace. + +Example: + +``` +seqcli workspace update --json '{...}' +``` + +| Option | Description | +| ------ | ----------- | +| `--json=VALUE` | The updated workspace in JSON format; this can be produced using `seqcli workspace list --json` | +| `--json-stdin` | Read the updated workspace as JSON from `STDIN` | +| `-s`, `--server=VALUE` | The URL of the Seq server; by default the `connection.serverUrl` config value will be used | +| `-a`, `--apikey=VALUE` | The API key to use when connecting to the server; by default the `connection.apiKey` config value will be used | +| `--profile=VALUE` | A connection profile to use; by default the `connection.serverUrl` and `connection.apiKey` config values will be used | + ## Extraction patterns The `seqcli ingest` command can be used for parsing plain text logs into structured log events.