diff --git a/content/influxdb/v2.0/reference/cli/influx/_index.md b/content/influxdb/v2.0/reference/cli/influx/_index.md index 7c44c57a4..1545c95bb 100644 --- a/content/influxdb/v2.0/reference/cli/influx/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/_index.md @@ -22,26 +22,6 @@ influx [flags] influx [command] ``` -{{% note %}} -#### Set your credentials - -1. To avoid having to pass your InfluxDB [authentication token](/influxdb/v2.0/security/tokens/view-tokens/) with each `influx` command, set up a configuration profile if you haven't already. -2. To see if you have a configuration profile, run `influx config`. If nothing is displayed, you don't have a configuration profile. -3. To configure a profile, in a terminal, run the following command: - - ```sh - # Set up a configuration profile - influx config create -n default \ - -u http://localhost:8086 \ - -o example-org \ - -t mySuP3rS3cr3tT0keN \ - -a - ``` - - This configures a new profile named `default` and makes the profile active so commands run against this instance. - For more detail, see [influx config](/influxdb/v2.0/reference/cli/influx/config/). -{{% /note %}} - ## Commands | Command | Description | @@ -67,18 +47,67 @@ influx [command] | [template](/influxdb/v2.0/reference/cli/influx/template) | Summarize and validate an InfluxDB template | | [transpile](/influxdb/v2.0/reference/cli/influx/transpile) | Manually transpile an InfluxQL query to Flux | | [user](/influxdb/v2.0/reference/cli/influx/user) | User management commands | +| [v1](/influxdb/v2.0/reference/cli/influx/v1) | Work with the v1 compatibility API | | [version](/influxdb/v2.0/reference/cli/influx/version) | Print the influx CLI version | | [write](/influxdb/v2.0/reference/cli/influx/write) | Write points to InfluxDB | -## Mapped environment variables - -Some `influx` CLI flags are mapped to environment variables. -Mapped flags get the value of the environment variable. -To override environment variables, set the flag explicitly in your command. - ## Flags | Flag | | Description | |:---- |:--- |:----------- | | `-h` | `--help` | Help for the `influx` command | +## Patterns and conventions +The `influx` CLI utilizes the following patterns and conventions: + +- [Easily provide required authentication credentials](#easily-provide-required-authentication-credentials) +- [Mapped environment variables](#mapped-environment-variables) +- [Shorthand and longhand flags](#shorthand-and-longhand-flags) +- [Flag input types](#flag-input-types) + +### Easily provide required authentication credentials +To avoid having to pass your InfluxDB **host**, **authentication token**, and **organization** +with each command, store them in an `influx` CLI configuration (config). +`influx` commands that require these credentials will automatically retrieve these +credentials from the active config. + +Use the [`influx config create` command](/influxdb/v2.0/reference/cli/influx/config/create/) +to create a new `influx` CLI config and set it as active: + +```sh +influx config create --config-name <config-name> \ + --host-url http://localhost:8086 \ + --org <your-org> \ + --token <your-auth-token \ + --active +``` + +### Mapped environment variables +Some `influx` CLI flags are mapped to environment variables. +Mapped flags get the value of the environment variable. +To override environment variables, set the flag explicitly in your command. + +### Shorthand and longhand flags +Many `influx` CLI flags support both shorthand and longhand forms. + +- **shorthand:** a shorthand flag begins with a single hyphen followed by a single letter (for example: `-c`). +- **longhand:** a longhand flag starts with two hyphens followed by a multi-letter, + hyphen-spaced flag name (for example: `--active-config`). + +Commands can use both shorthand and longhand flags in a single execution. + +### Flag input types +`influx` CLI flags use the support the following input types: + +#### string +Text string, but the flag can be used **only once** per command execution. + +#### stringArray +Single text string, but the flag can be used **multiple times** per command execution. + +#### integer +Sequence of digits representing an integer value. + +#### duration +Length of time represented by an integer and a duration unit +(`ns`, `us`, `µs`, `ms`, `s`, `m`, `h`, `d`, `w`). diff --git a/content/influxdb/v2.0/reference/cli/influx/apply/_index.md b/content/influxdb/v2.0/reference/cli/influx/apply/_index.md index e95e683a6..d01ddfe65 100644 --- a/content/influxdb/v2.0/reference/cli/influx/apply/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/apply/_index.md @@ -45,6 +45,9 @@ influx apply [flags] | `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` | ## Examples + +{{< cli/influx-creds-note >}} + ```sh # Apply a template from a file. influx apply -f path/to/template.json diff --git a/content/influxdb/v2.0/reference/cli/influx/backup/_index.md b/content/influxdb/v2.0/reference/cli/influx/backup/_index.md index 2859f305f..511d63649 100644 --- a/content/influxdb/v2.0/reference/cli/influx/backup/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/backup/_index.md @@ -1,6 +1,6 @@ --- title: influx backup -description: The `influx backup` command backs up data stored in InfluxDB. +description: The `influx backup` command backs up data stored in InfluxDB to a specified directory. menu: influxdb_2_0_ref: name: influx backup @@ -11,20 +11,44 @@ related: - /influxdb/v2.0/backup-restore/backup/ --- -The `influx backup` command backs up data stored in InfluxDB. +The `influx backup` command backs up data stored in InfluxDB to a specified directory. ## Usage ``` -influx backup [flags] +influx backup [flags] path ``` ## Flags -| Flag | | Description | Input type | {{< cli/mapped >}} | -|------|-------------------|-------------------------------------------------------------|------------|--------------------| -| `-c` | `--active-config` | CLI configuration to use for command | string | | -| | `--bucket-id` | ID of the bucket to back up from | string | | -| `-b` | `--bucket` | Name of the bucket to back up from | string | | -| `-h` | `--help` | Help for the `backup` command | | | -| | `--host` | HTTP address of InfluxDB (default: `http://localhost:8086`) | string | `INFLUX_HOST` | -| | `--skip-verify` | Skip TLS certificate verification | string | | -| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` | +| Flag | | Description | Input type | {{< cli/mapped >}} | +|------|-------------------|------------------------------------------------------------- |------------|-------------------- | +| `-c` | `--active-config` | CLI configuration to use for command | string | | +| | `--bucket-id` | ID of the bucket to back up from | string | | +| `-b` | `--bucket` | Name of the bucket to back up from | string | | +| | `--configs-path` | Path to `influx` CLI configurations (default `~/.influxdbv2/configs`) | string |`INFLUX_CONFIGS_PATH` | +| `-h` | `--help` | Help for the `backup` command | | | +| | `--hide-headers` | Hide table headers (default `false`) | | `INFLUX_HIDE_HEADERS` | +| | `--host` | HTTP address of InfluxDB (default: `http://localhost:8086`) | string | `INFLUX_HOST` | +| | `--json` | Output data as JSON (default `false`) | | `INFLUX_OUTPUT_JSON` | +| `-o` | `--org` | Organization name | string | `INFLUX_ORG` | +| | `--org-id` | Organization ID | string | `INFLUX_ORG_ID` | +| | `--skip-verify` | Skip TLS certificate verification | string | | +| `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` | + +## Examples + +{{< cli/influx-creds-note >}} + +##### Back up all data to a directory +```sh +influx backup /path/to/backup/dir/ +``` + +##### Back up all data to the current working directory +```sh +influx backup ./ +``` + +##### Back up a specific bucket to a directory +```sh +influx backup --bucket example-bucket /path/to/backup/dir/ +``` \ No newline at end of file diff --git a/content/influxdb/v2.0/reference/cli/influx/dashboards/_index.md b/content/influxdb/v2.0/reference/cli/influx/dashboards/_index.md index 44a05b7d5..598f002bb 100644 --- a/content/influxdb/v2.0/reference/cli/influx/dashboards/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/dashboards/_index.md @@ -33,6 +33,9 @@ influx dashboards [flags] | `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` | ## Examples + +{{< cli/influx-creds-note >}} + ```sh # List all dashboards influx dashboards diff --git a/content/influxdb/v2.0/reference/cli/influx/delete/_index.md b/content/influxdb/v2.0/reference/cli/influx/delete/_index.md index cfd5bda52..ede8cc213 100644 --- a/content/influxdb/v2.0/reference/cli/influx/delete/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/delete/_index.md @@ -40,6 +40,8 @@ Running `influx delete` without the `-p` or `--predicate` flag deletes all data ## Examples +{{< cli/influx-creds-note >}} + ##### Delete all points in a measurement ```sh influx delete \ diff --git a/content/influxdb/v2.0/reference/cli/influx/export/_index.md b/content/influxdb/v2.0/reference/cli/influx/export/_index.md index 2d59901d2..9ad212dea 100644 --- a/content/influxdb/v2.0/reference/cli/influx/export/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/export/_index.md @@ -61,6 +61,9 @@ influx export [command] | | `--variable-names` | Comma-separated list of variable names | string | | ## Examples + +{{< cli/influx-creds-note >}} + ```sh # Export buckets by ID influx export --buckets=$ID1,$ID2,$ID3 diff --git a/content/influxdb/v2.0/reference/cli/influx/export/all.md b/content/influxdb/v2.0/reference/cli/influx/export/all.md index dd6036327..510a31353 100644 --- a/content/influxdb/v2.0/reference/cli/influx/export/all.md +++ b/content/influxdb/v2.0/reference/cli/influx/export/all.md @@ -43,6 +43,8 @@ influx export all [flags] ## Examples +{{< cli/influx-creds-note >}} + ### Export all resources in an organization as a template ```sh influx export all --org $INFLUX_ORG diff --git a/content/influxdb/v2.0/reference/cli/influx/export/stack.md b/content/influxdb/v2.0/reference/cli/influx/export/stack.md index 32e531368..3b773a9f9 100644 --- a/content/influxdb/v2.0/reference/cli/influx/export/stack.md +++ b/content/influxdb/v2.0/reference/cli/influx/export/stack.md @@ -32,6 +32,9 @@ influx export stack <stack_id> [flags] | `-t` | `--token` | Authentication token | string | `INFLUX_TOKEN` | ## Examples + +{{< cli/influx-creds-note >}} + ```sh # Export a stack as a template influx export stack $STACK_ID diff --git a/content/influxdb/v2.0/reference/cli/influx/stacks/init.md b/content/influxdb/v2.0/reference/cli/influx/stacks/init.md index eeebb3e8f..02d627fd3 100644 --- a/content/influxdb/v2.0/reference/cli/influx/stacks/init.md +++ b/content/influxdb/v2.0/reference/cli/influx/stacks/init.md @@ -37,6 +37,8 @@ influx stacks init [flags] ## Examples +{{< cli/influx-creds-note >}} + ### Initialize a stack with a name and description ```sh diff --git a/content/influxdb/v2.0/reference/cli/influx/stacks/update.md b/content/influxdb/v2.0/reference/cli/influx/stacks/update.md index 113f12816..00bbce6a5 100644 --- a/content/influxdb/v2.0/reference/cli/influx/stacks/update.md +++ b/content/influxdb/v2.0/reference/cli/influx/stacks/update.md @@ -45,6 +45,9 @@ the added resources. {{% /warn %}} ## Examples + +{{< cli/influx-creds-note >}} + ```sh # Update a stack with a name and description influx stack update \ diff --git a/content/influxdb/v2.0/reference/cli/influx/telegrafs/_index.md b/content/influxdb/v2.0/reference/cli/influx/telegrafs/_index.md index eb6994f1d..2f9050e24 100644 --- a/content/influxdb/v2.0/reference/cli/influx/telegrafs/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/telegrafs/_index.md @@ -40,6 +40,9 @@ influx telegrafs [command] | | `--org-id` | Organization ID | string | `INFLUX_ORG_ID` | ## Examples + +{{< cli/influx-creds-note >}} + ```sh # List all known Telegraf configurations influx telegrafs diff --git a/content/influxdb/v2.0/reference/cli/influx/telegrafs/create.md b/content/influxdb/v2.0/reference/cli/influx/telegrafs/create.md index 4b50cdc80..73584b17c 100644 --- a/content/influxdb/v2.0/reference/cli/influx/telegrafs/create.md +++ b/content/influxdb/v2.0/reference/cli/influx/telegrafs/create.md @@ -33,6 +33,9 @@ influx telegrafs create [flags] | | `--org-id` | Organization ID | string | `INFLUX_ORG_ID` | ## Examples + +{{< cli/influx-creds-note >}} + ```sh # Create a new Telegraf configuration influx telegrafs create \ diff --git a/content/influxdb/v2.0/reference/cli/influx/telegrafs/rm.md b/content/influxdb/v2.0/reference/cli/influx/telegrafs/rm.md index 1dfd62e57..7d837ec15 100644 --- a/content/influxdb/v2.0/reference/cli/influx/telegrafs/rm.md +++ b/content/influxdb/v2.0/reference/cli/influx/telegrafs/rm.md @@ -30,6 +30,9 @@ influx telegrafs rm [flags] | | `--json` | Output data as json | | `$INFLUX_OUTPUT_JSON` | ## Examples + +{{< cli/influx-creds-note >}} + ```sh # Remove a single Telegraf configuration influx telegrafs rm -i $ID diff --git a/content/influxdb/v2.0/reference/cli/influx/telegrafs/update.md b/content/influxdb/v2.0/reference/cli/influx/telegrafs/update.md index fe119940b..06405de0f 100644 --- a/content/influxdb/v2.0/reference/cli/influx/telegrafs/update.md +++ b/content/influxdb/v2.0/reference/cli/influx/telegrafs/update.md @@ -33,6 +33,9 @@ influx telegrafs update [flags] | | `--org-id` | Organization ID | string | `INFLUX_ORG_ID` | ## Examples + +{{< cli/influx-creds-note >}} + ```sh # Update a Telegraf configuration influx telegrafs update \ diff --git a/content/influxdb/v2.0/reference/cli/influx/v1/auth/create.md b/content/influxdb/v2.0/reference/cli/influx/v1/auth/create.md index 631e75f59..70e95aa86 100644 --- a/content/influxdb/v2.0/reference/cli/influx/v1/auth/create.md +++ b/content/influxdb/v2.0/reference/cli/influx/v1/auth/create.md @@ -39,6 +39,8 @@ influx v1 auth create [flags] ## Examples +{{< cli/influx-creds-note >}} + ##### Create a new authorization with read and write permissions ```sh // Create an authorization with read and write access to bucket 00xX00o0X001 diff --git a/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/create.md b/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/create.md index 8dba83eb1..1028cc964 100644 --- a/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/create.md +++ b/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/create.md @@ -38,6 +38,8 @@ influx v1 dbrp create [flags] ## Examples +{{< cli/influx-creds-note >}} + ##### Create a DBRP mapping ```sh influx v1 dbrp create \ diff --git a/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/list.md b/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/list.md index 363b2138b..7855b11fc 100644 --- a/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/list.md +++ b/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/list.md @@ -39,6 +39,8 @@ influx v1 dbrp list [flags] ## Examples +{{< cli/influx-creds-note >}} + ##### List all DBRP mappings in your organization ```sh influx v1 dbrp list diff --git a/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/update.md b/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/update.md index 5ae442951..3c643c6a2 100644 --- a/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/update.md +++ b/content/influxdb/v2.0/reference/cli/influx/v1/dbrp/update.md @@ -36,6 +36,8 @@ influx v1 dbrp update [flags] ## Examples +{{< cli/influx-creds-note >}} + ##### Set a DBRP mapping as default ```sh influx v1 dbrp update \ diff --git a/content/influxdb/v2.0/reference/cli/influx/write/_index.md b/content/influxdb/v2.0/reference/cli/influx/write/_index.md index 707339e12..4e8b0dcc2 100644 --- a/content/influxdb/v2.0/reference/cli/influx/write/_index.md +++ b/content/influxdb/v2.0/reference/cli/influx/write/_index.md @@ -62,6 +62,8 @@ influx write [command] ## Examples +{{< cli/influx-creds-note >}} + - [Write line protocol](#line-protocol) - [via stdin](#write-line-protocol-via-stdin) - [from a file](#write-line-protocol-from-a-file) diff --git a/layouts/partials/article/related.html b/layouts/partials/article/related.html index 59782e2e9..5b0a1d8aa 100644 --- a/layouts/partials/article/related.html +++ b/layouts/partials/article/related.html @@ -5,10 +5,11 @@ <ul> {{ range .Params.related }} <!-- If an external link or API link --> - {{ if or (in . "http") (in . "/v2.0/api") }} + {{ if or (in . "http") (in . "/v2.0/api") (in . ", ")}} {{ $link := replaceRE `\,\s(.*)$` "" . }} {{ $title := replaceRE `^(\S*\,\s)` "" . }} - <li><a href="{{ $link }}" target="_blank">{{ $title }}</a></li> + {{ $target := cond (in . "http") "_blank" "" }} + <li><a href="{{ $link }}" target="{{ $target }}">{{ $title }}</a></li> <!-- If path is using the latest shortcode --> {{ else if (in . "{{< latest") }} diff --git a/layouts/shortcodes/cli/influx-creds-note.html b/layouts/shortcodes/cli/influx-creds-note.html new file mode 100644 index 000000000..1591ca14c --- /dev/null +++ b/layouts/shortcodes/cli/influx-creds-note.html @@ -0,0 +1,7 @@ +<div class="note block"> + <p> + The examples below assume your InfluxDB <strong>host</strong>, <strong>organization</strong>, and <strong>token</strong> are + provided by the <a href="/influxdb/v2.0/reference/cli/influx/config">active <code>influx</code> CLI configuration</a>. + If you do not have a CLI configuration setup, use the appropriate flags to provide these required credentials. + </p> +</div> \ No newline at end of file