Skip to content

Commit 52e6eec

Browse files
jstirnamanjstirnaman
committed
feat: Update InfluxDB 3 CLI documentation for v3.2.0 features
- Add influxdb3 show license command documentation for Enterprise - Update create database command with --retention-period option - Update create table command with Enterprise --retention-period option - Update delete database/table commands with --hard-delete options - Update CLI command index to include license command - Update planning documentation for CLI sync process - Closes #6160
1 parent 29da031 commit 52e6eec

File tree

7 files changed

+277
-26
lines changed

7 files changed

+277
-26
lines changed

‎content/influxdb3/enterprise/reference/cli/influxdb3/show/license.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: influxdb3 show license
3+
description: >
4+
The `influxdb3 show license` command displays license information for your
5+
InfluxDB 3 Enterprise server.
6+
menu:
7+
influxdb3_enterprise:
8+
parent: influxdb3 show
9+
name: influxdb3 show license
10+
weight: 300
11+
---
12+
13+
The `influxdb3 show license` command displays license information for your {{< product-name >}} instance.
14+
15+
{{% show-in "enterprise" %}}
16+
This command is only available in InfluxDB 3 Enterprise.
17+
{{% /show-in %}}
18+
19+
## Usage
20+
21+
<!--pytest.mark.skip-->
22+
23+
```bash
24+
influxdb3 show license [OPTIONS]
25+
```
26+
27+
## Options
28+
29+
| Option | | Description |
30+
| :----- | :----------- | :--------------------------------------------------------------------------------------- |
31+
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
32+
| | `--cluster-id` | _({{< req >}})_ Cluster identifier |
33+
| | `--node-id` | _({{< req >}})_ Node identifier |
34+
| | `--object-store` | _({{< req >}})_ Object store type (file, memory, s3, gcs, azure) |
35+
| | `--token` | Authentication token |
36+
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
37+
| `-h` | `--help` | Print help information |
38+
| | `--help-all` | Print detailed help information |
39+
40+
> [!Note]
41+
> **CLI help documentation bug in v3.2.0**
42+
>
43+
> The `influxdb3 show license --help` output in v3.2.0 does not display the required `--object-store`, `--cluster-id`, and `--node-id` options and related object store configuration options.
44+
> This command requires object store configuration and cluster/node identification to function properly.
45+
46+
### Additional object store options
47+
48+
Depending on the `--object-store` type specified, additional configuration options may be required:
49+
50+
- **S3**: AWS credentials and bucket configuration
51+
- **GCS**: Google Cloud credentials and bucket configuration
52+
- **Azure**: Azure credentials and container configuration
53+
- **File**: Local file system path configuration
54+
55+
### Option environment variables
56+
57+
You can use the following environment variables to set command options:
58+
59+
| Environment Variable | Option |
60+
| :------------------------ | :----------- |
61+
| `INFLUXDB3_HOST_URL` | `--host` |
62+
| `INFLUXDB3_AUTH_TOKEN` | `--token` |
63+
64+
## Examples
65+
66+
### Display license information with file object store
67+
68+
{{% code-placeholders "AUTH_TOKEN|CLUSTER_ID|NODE_ID" %}}
69+
70+
<!--pytest.mark.skip-->
71+
72+
```bash
73+
influxdb3 show license \
74+
--cluster-id CLUSTER_ID \
75+
--node-id NODE_ID \
76+
--object-store file \
77+
--token AUTH_TOKEN
78+
```
79+
80+
{{% /code-placeholders %}}
81+
82+
In the example above, replace the following:
83+
84+
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}:
85+
Authentication token
86+
- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}:
87+
Your cluster identifier
88+
- {{% code-placeholder-key %}}`NODE_ID`{{% /code-placeholder-key %}}:
89+
Your node identifier
90+
91+
The command displays information about your Enterprise license, including license type, expiration date, and usage limits.

‎content/shared/influxdb3-cli/create/database.md

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,14 @@ You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environme
1919

2020
## Options
2121

22-
| Option | | Description |
23-
| :----- | :----------- | :--------------------------------------------------------------------------------------- |
24-
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
25-
| | `--token` | Authentication token |
26-
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
27-
| `-h` | `--help` | Print help information |
28-
| | `--help-all` | Print detailed help information |
22+
| Option | | Description |
23+
| :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
24+
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
25+
| | `--retention-period` | Database [retention period](/influxdb3/version/reference/glossary/#retention-period) ([duration](/influxdb3/version/reference/glossary/#duration) value, for example: `30d`, `24h`, `1h`) |
26+
| | `--token` | Authentication token |
27+
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
28+
| `-h` | `--help` | Print help information |
29+
| | `--help-all` | Print detailed help information |
2930

3031
### Option environment variables
3132

@@ -69,4 +70,14 @@ Flags override their associated environment variables.
6970
influxdb3 create database --token AUTH_TOKEN DATABASE_NAME
7071
```
7172

73+
### Create a database with a retention period
74+
75+
Creates a database with a specific retention period.
76+
77+
<!--pytest.mark.skip-->
78+
79+
```bash
80+
influxdb3 create database --retention-period 30d DATABASE_NAME
81+
```
82+
7283
{{% /code-placeholders %}}

‎content/shared/influxdb3-cli/create/table.md

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ influxdb3 create table [OPTIONS] \
2424

2525
## Options
2626

27+
{{% hide-in "enterprise" %}}
2728
| Option | | Description |
2829
| :----- | :----------- | :--------------------------------------------------------------------------------------- |
2930
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
@@ -34,6 +35,22 @@ influxdb3 create table [OPTIONS] \
3435
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
3536
| `-h` | `--help` | Print help information |
3637
| | `--help-all` | Print detailed help information |
38+
{{% /hide-in %}}
39+
40+
<!-- Using the show-in shortcode for only the retention-period option breaks the formatting in Core -->
41+
{{% show-in "enterprise" %}}
42+
| Option | | Description |
43+
| :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
44+
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
45+
| `-d` | `--database` | _({{< req >}})_ Name of the database to operate on |
46+
| | `--retention-period` | [Retention period](/influxdb3/version/reference/glossary/#retention-period) ([duration](/influxdb3/version/reference/glossary/#duration) value, for example: `30d`, `24h`, `1h`) for data in the table|
47+
| | `--token` | _({{< req >}})_ Authentication token |
48+
| | `--tags` | _({{< req >}})_ Comma-separated list of tag columns to include in the table |
49+
| | `--fields` | Comma-separated list of field columns and their types to include in the table |
50+
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
51+
| `-h` | `--help` | Print help information |
52+
| | `--help-all` | Print detailed help information |
53+
{{% /show-in %}}
3754

3855
> [!Important]
3956
>
@@ -90,6 +107,22 @@ influxdb3 create table \
90107
TABLE_NAME
91108
```
92109

110+
{{% show-in "enterprise" %}}
111+
### Create a table with a retention period
112+
113+
<!--pytest.mark.skip-->
114+
115+
```bash
116+
influxdb3 create table \
117+
--tags room,sensor_id \
118+
--fields temp:float64,hum:float64 \
119+
--retention-period 7d \
120+
--database DATABASE_NAME \
121+
--token AUTH_TOKEN \
122+
TABLE_NAME
123+
```
124+
{{% /show-in %}}
125+
93126
### Verification
94127

95128
Use the `SHOW TABLES` query to verify that the table was created successfully:
@@ -114,7 +147,7 @@ Example output:
114147
+---------------+--------------------+----------------------------+------------+
115148
```
116149

117-
>[!Note]
150+
> [!Note]
118151
> `SHOW TABLES` is an SQL query. It isn't supported in InfluxQL.
119152
120153
{{% /code-placeholders %}}

‎content/shared/influxdb3-cli/delete/database.md

Lines changed: 30 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,14 @@ influxdb3 delete database [OPTIONS] <DATABASE_NAME>
1717

1818
## Options
1919

20-
| Option | | Description |
21-
| :----- | :----------- | :--------------------------------------------------------------------------------------- |
22-
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
23-
| | `--token` | Authentication token |
24-
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
25-
| `-h` | `--help` | Print help information |
26-
| | `--help-all` | Print detailed help information |
20+
| Option | | Description |
21+
| :----- | :------------ | :--------------------------------------------------------------------------------------- |
22+
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
23+
| | `--hard-delete` | When to hard delete data (never/now/default/timestamp). Default behavior is a soft delete that allows recovery |
24+
| | `--token` | Authentication token |
25+
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
26+
| `-h` | `--help` | Print help information |
27+
| | `--help-all` | Print detailed help information |
2728

2829
### Option environment variables
2930

@@ -36,8 +37,8 @@ You can use the following environment variables to set command options:
3637

3738
## Examples
3839

39-
- [Delete a database](#delete-a-new-database)
40-
- [Delete a database while specifying the token inline](#delete-a-new-database-while-specifying-the-token-inline)
40+
- [Delete a database](#delete-a-database)
41+
- [Delete a database while specifying the token inline](#delete-a-database-while-specifying-the-token-inline)
4142

4243
In the examples below, replace the following:
4344

@@ -64,4 +65,24 @@ influxdb3 delete database DATABASE_NAME
6465
influxdb3 delete database --token AUTH_TOKEN DATABASE_NAME
6566
```
6667

68+
### Hard delete a database immediately
69+
70+
Permanently delete a database and all its data immediately without the ability to recover.
71+
72+
<!--pytest.mark.skip-->
73+
74+
```bash
75+
influxdb3 delete database --hard-delete now DATABASE_NAME
76+
```
77+
78+
### Hard delete a database at a specific time
79+
80+
Schedule a database for permanent deletion at a specific timestamp.
81+
82+
<!--pytest.mark.skip-->
83+
84+
```bash
85+
influxdb3 delete database --hard-delete "2024-01-01T00:00:00Z" DATABASE_NAME
86+
```
87+
6788
{{% /code-placeholders %}}

‎content/shared/influxdb3-cli/delete/table.md

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,15 @@ influxdb3 delete table [OPTIONS] --database <DATABASE_NAME> <TABLE_NAME>
1515

1616
## Options
1717

18-
| Option | | Description |
19-
| :----- | :----------- | :--------------------------------------------------------------------------------------- |
20-
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
21-
| `-d` | `--database` | _({{< req >}})_ Name of the database to operate on |
22-
| | `--token` | _({{< req >}})_ Authentication token |
23-
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
24-
| `-h` | `--help` | Print help information |
25-
| | `--help-all` | Print detailed help information |
18+
| Option | | Description |
19+
| :----- | :------------ | :--------------------------------------------------------------------------------------- |
20+
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
21+
| `-d` | `--database` | _({{< req >}})_ Name of the database to operate on |
22+
| | `--hard-delete` | When to hard delete data (never/now/default/timestamp). Default behavior is a soft delete that allows recovery |
23+
| | `--token` | _({{< req >}})_ Authentication token |
24+
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
25+
| `-h` | `--help` | Print help information |
26+
| | `--help-all` | Print detailed help information |
2627

2728
### Option environment variables
2829

@@ -49,9 +50,23 @@ influxdb3 delete table \
4950
TABLE_NAME
5051
```
5152

53+
### Hard delete a table immediately
54+
55+
Permanently delete a table and all its data immediately without the ability to recover.
56+
57+
<!--pytest.mark.skip-->
58+
59+
```bash
60+
influxdb3 delete table \
61+
--database DATABASE_NAME \
62+
--token AUTH_TOKEN \
63+
--hard-delete now \
64+
TABLE_NAME
65+
```
66+
5267
{{% /code-placeholders %}}
5368

54-
In the example above, replace the following:
69+
In the examples above, replace the following:
5570

5671
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
5772
Database name

‎content/shared/influxdb3-cli/show/_index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ influxdb3 show <SUBCOMMAND>
1414
| Subcommand | Description |
1515
| :---------------------------------------------------------------------- | :--------------------------------------------- |
1616
| [databases](/influxdb3/version/reference/cli/influxdb3/show/databases/) | List database |
17+
{{% show-in "enterprise" %}}| [license](/influxdb3/version/reference/cli/influxdb3/show/license/) | Display license information |{{% /show-in %}}
1718
| [system](/influxdb3/version/reference/cli/influxdb3/show/system/) | Display system table data |
1819
| [tokens](/influxdb3/version/reference/cli/influxdb3/show/tokens/) | List authentication tokens |
1920
| help | Print command help or the help of a subcommand |

‎plans/cli-docs-sync/plan.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Plan: Update InfluxDB 3 CLI Reference Documentation
2+
3+
## Automation and Process Improvements
4+
5+
### Immediate Improvements:
6+
1. **Create CLI documentation sync script:**
7+
```bash
8+
# Script: /Users/ja/Documents/github/docs-v2/scripts/sync-cli-docs.sh
9+
# - Extract help text from influxdb3 CLI at /Users/ja/.influxdb//influxdb3
10+
# - Compare with existing docs
11+
# - Generate report of differences
12+
# - Auto-update basic command syntax
13+
# - Real-time CLI verification capability established
14+
```
15+
16+
2. **Establish documentation standards:**
17+
- Standardize frontmatter across CLI docs
18+
- Create templates for command documentation
19+
- Define Enterprise vs Core content patterns using Hugo shortcodes
20+
21+
### Long-term Automation Strategy:
22+
1. **CI/CD Integration:**
23+
- Add GitHub Actions workflow to detect CLI changes
24+
- Auto-generate CLI help extraction on new releases
25+
- Create pull requests for documentation updates
26+
27+
2. **Release Process Integration:**
28+
- Include CLI documentation review in release checklist
29+
- Link release notes to specific CLI documentation updates
30+
- Automated cross-referencing between release notes and CLI docs
31+
32+
3. **Content Management Improvements:**
33+
- Use Hugo shortcodes for Enterprise-specific content
34+
- Implement version-aware documentation
35+
- Create shared content templates for common CLI patterns
36+
37+
## Phase 4: Validation and Testing
38+
39+
### Content accuracy verification:
40+
- ✅ **CLI Access Available**: Direct verification via `influxdb3 --help` commands
41+
- ✅ **Real-time Validation**: All commands and options verified against actual CLI output
42+
- **Process**: Use `influxdb3 [command] --help` to validate documentation accuracy
43+
- **Verification**: Cross-reference documented options with actual CLI behavior
44+
45+
### Documentation completeness check:
46+
- Ensure all v3.2.0 features are documented
47+
- Verify examples and use cases
48+
- Check internal links and cross-references
49+
50+
## Suggested Recurring Process
51+
52+
### Pre-release (during development):
53+
- Monitor CLI changes in pull requests
54+
- Update documentation as features are added
55+
- Maintain CLI help extraction automation
56+
57+
### At release (when tagging versions):
58+
- Run automated CLI documentation sync
59+
- Review and approve auto-generated updates
60+
- Publish updated documentation
61+
62+
### Post-release (after release):
63+
- Validate documentation accuracy
64+
- Gather user feedback on CLI documentation
65+
- Plan improvements for next cycle
66+
67+
## Related Documentation Paths
68+
69+
### InfluxDB 3 Product Documentation (affects CLI usage examples):
70+
- `/content/influxdb3/core/write-data/influxdb3-cli.md`
71+
- `/content/influxdb3/enterprise/write-data/influxdb3-cli.md`
72+
- `/content/shared/influxdb3-write-guides/influxdb3-cli.md`
73+
74+
### Admin Documentation (affects retention and license features):
75+
- `/content/influxdb3/core/admin/`
76+
- `/content/influxdb3/enterprise/admin/`
77+
- `/content/influxdb3/enterprise/admin/license.md`
78+
79+
This plan ensures comprehensive documentation updates for v3.2.0 while establishing sustainable processes for future releases.

0 commit comments

Comments
 (0)