From 72c0ffdc2fa7b71f1f7f58f14aa32354a01e9209 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 6 Aug 2025 11:38:45 -0600 Subject: [PATCH 1/9] add embedded cluster cli docs reference --- docs/reference/embedded-cluster-install.mdx | 6 ++---- sidebars.js | 19 ++++++++++++++++++- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/reference/embedded-cluster-install.mdx b/docs/reference/embedded-cluster-install.mdx index 65df2a0903..a641ad89a2 100644 --- a/docs/reference/embedded-cluster-install.mdx +++ b/docs/reference/embedded-cluster-install.mdx @@ -3,17 +3,15 @@ import ProxyRequirements from "../partials/embedded-cluster/_proxy-install-reqs. import ProxyEnvVars from "../partials/embedded-cluster/_proxy-env-vars.mdx" import DeprecatedPrivateCa from "../partials/embedded-cluster/_deprecated-private-ca.mdx" -# Embedded Cluster Install Command Options +# install This topic describes the options available with the Embedded Cluster install command. For more information about how to install with Embedded Cluster, see [Online Installation with Embedded Cluster](/enterprise/installing-embedded) or [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded). ## Usage ```bash -sudo ./APP_SLUG install --license PATH_TO_LICENSE [flags] +sudo ./ install --license [flags] ``` -* `APP_SLUG` is the unique application slug -* `PATH_TO_LICENSE` is the path to the customer license ## Flags diff --git a/sidebars.js b/sidebars.js index 233c57fa5f..50308fa4c8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -251,7 +251,6 @@ const sidebars = { 'enterprise/installing-embedded', 'enterprise/installing-embedded-air-gap', 'enterprise/installing-embedded-automation', - 'reference/embedded-cluster-install', ], }, 'enterprise/embedded-manage-nodes', @@ -259,6 +258,24 @@ const sidebars = { 'vendor/embedded-troubleshooting', 'enterprise/embedded-tls-certs', 'vendor/embedded-disaster-recovery', + { + type: 'category', + label: 'Embedded Cluster Commands', + items: [ + 'reference/embedded-cluster-admin-console', + 'reference/embedded-cluster-completion', + 'reference/embedded-cluster-enable-ha', + 'reference/embedded-cluster-install', + 'reference/embedded-cluster-join', + 'reference/embedded-cluster-join-print-command', + 'reference/embedded-cluster-reset', + 'reference/embedded-cluster-restore', + 'reference/embedded-cluster-shell', + 'reference/embedded-cluster-support-bundle', + 'reference/embedded-cluster-update', + 'reference/embedded-cluster-version', + ], + }, ], }, { From 7064f4c374fb2a7633fa8a5e8d3f8acb9048d6af Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 6 Aug 2025 11:42:39 -0600 Subject: [PATCH 2/9] add new files and edit xrefs --- .../installing-embedded-air-gap.mdx | 2 +- docs/enterprise/installing-embedded.mdx | 2 +- docs/partials/embedded-cluster/_port-reqs.mdx | 4 +- .../embedded-cluster/_requirements.mdx | 2 +- .../embedded-cluster-admin-console.mdx | 41 ++++ .../reference/embedded-cluster-completion.mdx | 60 ++++++ docs/reference/embedded-cluster-enable-ha.mdx | 26 +++ .../embedded-cluster-join-print-command.mdx | 42 ++++ docs/reference/embedded-cluster-join.mdx | 81 ++++++++ docs/reference/embedded-cluster-reset.mdx | 41 ++++ docs/reference/embedded-cluster-restore.mdx | 131 ++++++++++++ docs/reference/embedded-cluster-shell.mdx | 27 +++ .../embedded-cluster-support-bundle.mdx | 27 +++ docs/reference/embedded-cluster-update.mdx | 34 ++++ docs/reference/embedded-cluster-version.mdx | 58 ++++++ docs/release-notes/rn-embedded-cluster.md | 4 +- docs/templates/cli-docs.md | 191 ++++++++++++++++++ docs/vendor/embedded-disaster-recovery.mdx | 8 +- 18 files changed, 770 insertions(+), 11 deletions(-) create mode 100644 docs/reference/embedded-cluster-admin-console.mdx create mode 100644 docs/reference/embedded-cluster-completion.mdx create mode 100644 docs/reference/embedded-cluster-enable-ha.mdx create mode 100644 docs/reference/embedded-cluster-join-print-command.mdx create mode 100644 docs/reference/embedded-cluster-join.mdx create mode 100644 docs/reference/embedded-cluster-reset.mdx create mode 100644 docs/reference/embedded-cluster-restore.mdx create mode 100644 docs/reference/embedded-cluster-shell.mdx create mode 100644 docs/reference/embedded-cluster-support-bundle.mdx create mode 100644 docs/reference/embedded-cluster-update.mdx create mode 100644 docs/reference/embedded-cluster-version.mdx create mode 100644 docs/templates/cli-docs.md diff --git a/docs/enterprise/installing-embedded-air-gap.mdx b/docs/enterprise/installing-embedded-air-gap.mdx index 3db3bda12e..161fda6a4a 100644 --- a/docs/enterprise/installing-embedded-air-gap.mdx +++ b/docs/enterprise/installing-embedded-air-gap.mdx @@ -87,7 +87,7 @@ To install with Embedded Cluster in an air gap environment: Where `APP_SLUG` is the unique application slug. :::note - Embedded Cluster supports installation options such as installing behind a proxy and changing the data directory used by Embedded Cluster. For the list of flags supported with the Embedded Cluster `install` command, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). + Embedded Cluster supports installation options such as installing behind a proxy and changing the data directory used by Embedded Cluster. For the list of flags supported with the Embedded Cluster `install` command, see [install](/reference/embedded-cluster-install). ::: 1. When prompted, enter a password for accessing the KOTS Admin Console. diff --git a/docs/enterprise/installing-embedded.mdx b/docs/enterprise/installing-embedded.mdx index 370883fb1e..043c19a302 100644 --- a/docs/enterprise/installing-embedded.mdx +++ b/docs/enterprise/installing-embedded.mdx @@ -49,7 +49,7 @@ To install an application with Embedded Cluster: * `LICENSE_FILE` is the customer license.
:::note - Embedded Cluster supports installation options such as installing behind a proxy and changing the data directory used by Embedded Cluster. For the list of flags supported with the Embedded Cluster `install` command, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). + Embedded Cluster supports installation options such as installing behind a proxy and changing the data directory used by Embedded Cluster. For the list of flags supported with the Embedded Cluster `install` command, see [install](/reference/embedded-cluster-install). ::: 1. When prompted, enter a password for accessing the KOTS Admin Console. diff --git a/docs/partials/embedded-cluster/_port-reqs.mdx b/docs/partials/embedded-cluster/_port-reqs.mdx index 131f4b19d0..c973b4c086 100644 --- a/docs/partials/embedded-cluster/_port-reqs.mdx +++ b/docs/partials/embedded-cluster/_port-reqs.mdx @@ -34,10 +34,10 @@ The KOTS Admin Console requires that port 30000/TCP is open and available. Creat Additionally, port 30000 must be accessible by nodes joining the cluster. -If port 30000 is occupied, you can select a different port for the Admin Console during installation. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). +If port 30000 is occupied, you can select a different port for the Admin Console during installation. For more information, see [install](/reference/embedded-cluster-install). #### LAM Port The Local Artifact Mirror (LAM) requires that port 50000/TCP is open and available. -If port 50000 is occupied, you can select a different port for the LAM during installation. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). +If port 50000 is occupied, you can select a different port for the LAM during installation. For more information, see [install](/reference/embedded-cluster-install). diff --git a/docs/partials/embedded-cluster/_requirements.mdx b/docs/partials/embedded-cluster/_requirements.mdx index 7dc9213acd..ff53f5683b 100644 --- a/docs/partials/embedded-cluster/_requirements.mdx +++ b/docs/partials/embedded-cluster/_requirements.mdx @@ -8,7 +8,7 @@ * The disk on the host must have a maximum P99 write latency of 10 ms. This supports etcd performance and stability. For more information about the disk write latency requirements for etcd, see [Disks](https://etcd.io/docs/latest/op-guide/hardware/#disks) in _Hardware recommendations_ and [What does the etcd warning “failed to send out heartbeat on time” mean?](https://etcd.io/docs/latest/faq/) in the etcd documentation. -* The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/embedded-cluster`. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). +* The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/embedded-cluster`. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [install](/reference/embedded-cluster-install). Note that in addition to the primary data directory, Embedded Cluster creates directories and files in the following locations: diff --git a/docs/reference/embedded-cluster-admin-console.mdx b/docs/reference/embedded-cluster-admin-console.mdx new file mode 100644 index 0000000000..fab184b82d --- /dev/null +++ b/docs/reference/embedded-cluster-admin-console.mdx @@ -0,0 +1,41 @@ +# admin-console + +This topic describes the options available with the Embedded Cluster `admin-console` command. + +## Usage + +```bash +sudo ./ admin-console reset-password [flags] +``` + +## Commands + + + + + + + + + + +
CommandDescription
reset-password +

Reset the Admin Console password. If no password is provided, you will be prompted to enter a new one.

+
+ +## Flags + + + + + + + + + + + + +
FlagTypeDescription
`-h, --help` +

help for reset-password

+
\ No newline at end of file diff --git a/docs/reference/embedded-cluster-completion.mdx b/docs/reference/embedded-cluster-completion.mdx new file mode 100644 index 0000000000..f5cceeb3c9 --- /dev/null +++ b/docs/reference/embedded-cluster-completion.mdx @@ -0,0 +1,60 @@ +# completion + +This topic describes the options available with the Embedded Cluster `completion` command. + +## Usage + +```bash +sudo ./ completion [command] +``` + +## Commands + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
bash +

Generate the autocompletion script for bash

+
fish +

Generate the autocompletion script for fish

+
powershell +

Generate the autocompletion script for powershell

+
zsh +

Generate the autocompletion script for zsh

+
+ +## Flags + + + + + + + + + + + + +
FlagTypeDescription
`-h, --help` +

help for completion

+
+ diff --git a/docs/reference/embedded-cluster-enable-ha.mdx b/docs/reference/embedded-cluster-enable-ha.mdx new file mode 100644 index 0000000000..6fdabe3f08 --- /dev/null +++ b/docs/reference/embedded-cluster-enable-ha.mdx @@ -0,0 +1,26 @@ +# enable-ha + +This topic describes the options available with the Embedded Cluster `enable-ha` command. + +## Usage + +```bash +sudo ./ enable-ha [flags] +``` + +## Flags + + + + + + + + + + + + +
FlagTypeDescription
`-h, --help` +

help for enable-ha

+
\ No newline at end of file diff --git a/docs/reference/embedded-cluster-join-print-command.mdx b/docs/reference/embedded-cluster-join-print-command.mdx new file mode 100644 index 0000000000..7faa4674d8 --- /dev/null +++ b/docs/reference/embedded-cluster-join-print-command.mdx @@ -0,0 +1,42 @@ +# join print-command + +This topic describes the options available with the Embedded Cluster `join print-command` command. + +## Usage + +```bash +sudo ./ join print-command [flags] +``` + +## Commands + + + + + + + + + + +
CommandDescription
run-preflights +

Run join host preflights for the application.

+
+ +## Flags + + + + + + + + + + + + +
FlagTypeDescription
`-h, --help` +

help for print-command

+
+ diff --git a/docs/reference/embedded-cluster-join.mdx b/docs/reference/embedded-cluster-join.mdx new file mode 100644 index 0000000000..a114b46315 --- /dev/null +++ b/docs/reference/embedded-cluster-join.mdx @@ -0,0 +1,81 @@ +# join + +This topic describes the options available with the Embedded Cluster `join` command. + +## Usage + +```bash +sudo ./ join [flags] +``` + +```bash +sudo ./ join [command] +``` + +## Commands + + + + + + + + + + +
CommandDescription
run-preflights +

Run join host preflights for the application.

+
+ +## Flags + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescriptionDescription
`--airgap-bundle`string +

Path to the air gap bundle. If set, the installation will complete without internet access.

+
`-h, --help` +

help for join

+
`--ignore-host-preflights` +

Run host preflight checks, but prompt the user to continue if they fail instead of exiting.

+
`--network-interface`string +

The network interface to use for the cluster.

+
`--no-ha` +

Do not prompt for or enable high availability.

+
`-y, --yes` +

Assume yes to all prompts.

+
+ diff --git a/docs/reference/embedded-cluster-reset.mdx b/docs/reference/embedded-cluster-reset.mdx new file mode 100644 index 0000000000..7dd6264e0f --- /dev/null +++ b/docs/reference/embedded-cluster-reset.mdx @@ -0,0 +1,41 @@ +# reset + +This topic describes the options available with the Embedded Cluster `reset` command. + +## Usage + +```bash +sudo ./ reset [flags] +``` + +## Flags + + + + + + + + + + + + + + + + + + + + + + +
FlagTypeDescription
`--force` +

Ignore errors encountered when resetting the node (implies --yes)

+
`-h, --help` +

help for reset

+
`-y, --yes` +

Assume yes to all prompts.

+
+ diff --git a/docs/reference/embedded-cluster-restore.mdx b/docs/reference/embedded-cluster-restore.mdx new file mode 100644 index 0000000000..da3bd0a970 --- /dev/null +++ b/docs/reference/embedded-cluster-restore.mdx @@ -0,0 +1,131 @@ +# restore + +This topic describes the options available with the Embedded Cluster `restore` command. + +## Usage + +```bash +sudo ./ restore [flags] +``` + +## Flags + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagTypeDescription
`--airgap-bundle`string +

Path to the air gap bundle. If set, the installation will complete without internet access.

+
`--cidr`string +

CIDR block of available private IP addresses (/16 or larger) (default "10.244.0.0/16")

+
`--data-dir`string +

Path to the data directory (default "/var/lib/embedded-cluster")

+
`-h, --help` +

help for restore

+
`--http-proxy`string +

HTTP proxy to use for the installation

+
`--https-proxy`string +

HTTPS proxy to use for the installation

+
`--ignore-host-preflights` +

Allow bypassing host preflight failures

+
`--local-artifact-mirror-port`int +

Port on which the Local Artifact Mirror will be served (default 50000)

+
`--network-interface`string +

The network interface to use for the cluster

+
`--no-proxy`string +

Comma-separated list of hosts for which not to use a proxy

+
`--private-ca`strings +

Path to a trusted private CA certificate file

+
`--skip-store-validation` +

Skip validation of the backup storage location

+
`-y, --yes` +

Assume yes to all prompts.

+
+ +$ SOURCE CONTENT +Restore a gitea-two cluster + +Usage: + gitea-two restore [flags] + +Flags: + --airgap-bundle string Path to the air gap bundle. If set, the installation will complete without internet access. + --cidr string CIDR block of available private IP addresses (/16 or larger) (default "10.244.0.0/16") + --data-dir string Path to the data directory (default "/var/lib/embedded-cluster") + -h, --help help for restore + --http-proxy string HTTP proxy to use for the installation + --https-proxy string HTTPS proxy to use for the installation + --ignore-host-preflights Allow bypassing host preflight failures + --local-artifact-mirror-port int Port on which the Local Artifact Mirror will be served (default 50000) + --network-interface string The network interface to use for the cluster + --no-proxy string Comma-separated list of hosts for which not to use a proxy + --private-ca strings Path to a trusted private CA certificate file + --skip-store-validation Skip validation of the backup storage location + -y, --yes Assume yes to all prompts. diff --git a/docs/reference/embedded-cluster-shell.mdx b/docs/reference/embedded-cluster-shell.mdx new file mode 100644 index 0000000000..9276a6de04 --- /dev/null +++ b/docs/reference/embedded-cluster-shell.mdx @@ -0,0 +1,27 @@ +# shell + +This topic describes the options available with the Embedded Cluster `shell` command. + +## Usage + +```bash +sudo ./ shell [flags] +``` + +## Flags + + + + + + + + + + + + +
FlagTypeDescription
`-h, --help` +

help for shell

+
+ diff --git a/docs/reference/embedded-cluster-support-bundle.mdx b/docs/reference/embedded-cluster-support-bundle.mdx new file mode 100644 index 0000000000..ec99880c70 --- /dev/null +++ b/docs/reference/embedded-cluster-support-bundle.mdx @@ -0,0 +1,27 @@ +# support-bundle + +This topic describes the options available with the Embedded Cluster `support-bundle` command. + +## Usage + +```bash +sudo ./ support-bundle [flags] +``` + +## Flags + + + + + + + + + + + + +
FlagTypeDescription
`-h, --help` +

help for support-bundle

+
+ diff --git a/docs/reference/embedded-cluster-update.mdx b/docs/reference/embedded-cluster-update.mdx new file mode 100644 index 0000000000..1b07a50035 --- /dev/null +++ b/docs/reference/embedded-cluster-update.mdx @@ -0,0 +1,34 @@ +# update + +This topic describes the options available with the Embedded Cluster `update` command. + +## Usage + +```bash +sudo ./ update [flags] +``` + +## Flags + + + + + + + + + + + + + + + + + +
FlagTypeDescription
`--airgap-bundle`string +

Path to the air gap bundle. If set, the installation will complete without internet access.

+
`-h, --help` +

help for update

+
+ diff --git a/docs/reference/embedded-cluster-version.mdx b/docs/reference/embedded-cluster-version.mdx new file mode 100644 index 0000000000..b8949a4584 --- /dev/null +++ b/docs/reference/embedded-cluster-version.mdx @@ -0,0 +1,58 @@ +# version + +This topic describes the options available with the Embedded Cluster `version` command. + +## Usage + +```bash +sudo ./ version [flags] +``` + +```bash +sudo ./ version [command] +``` + +## Commands + + + + + + + + + + + + + + + + + + +
CommandDescription
embedded-data +

Read the application data embedded in the cluster

+
list-images +

List images embedded in the cluster

+
metadata +

Print metadata about this release

+
+ +## Flags + + + + + + + + + + + + +
FlagTypeDescription
`-h, --help` +

help for version

+
+ diff --git a/docs/release-notes/rn-embedded-cluster.md b/docs/release-notes/rn-embedded-cluster.md index 7d831ea7b0..ec61afbc31 100644 --- a/docs/release-notes/rn-embedded-cluster.md +++ b/docs/release-notes/rn-embedded-cluster.md @@ -659,9 +659,9 @@ Released on October 23, 2024 ### New Features {#new-features-1-16-0} * Adds support for Kubernetes 1.30 and removes support for 1.28. -* Adds a `--data-dir` flag to the `install` and `restore` commands so the data directory can be specified. By default, the data directory is `/var/lib/embedded-cluster`. If the `--data-dir` flag was provided at install time, then the same data directory must be provided when restoring. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install) and [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). +* Adds a `--data-dir` flag to the `install` and `restore` commands so the data directory can be specified. By default, the data directory is `/var/lib/embedded-cluster`. If the `--data-dir` flag was provided at install time, then the same data directory must be provided when restoring. For more information, see [install](/reference/embedded-cluster-install) and [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). * Adds an `admin-console reset-password` command that allows resetting the password for the Admin Console. -* Adds a `--cidr` flag to the `install` command that replaces the `--pod-cidr` and `--service-cidr` flags. The CIDR range specified with the `--cidr` flag is split and used for both the Pod and Service CIDRs. See [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). +* Adds a `--cidr` flag to the `install` command that replaces the `--pod-cidr` and `--service-cidr` flags. The CIDR range specified with the `--cidr` flag is split and used for both the Pod and Service CIDRs. See [install](/reference/embedded-cluster-install). :::note The `--pod-cidr` and `--service-cidr` flags are hidden, but still functional. Replicated recommends that you update any automation that uses the `--pod-cidr` and `--service-cidr` flags to use the `--cidr` flag instead. diff --git a/docs/templates/cli-docs.md b/docs/templates/cli-docs.md new file mode 100644 index 0000000000..ade3dd28b3 --- /dev/null +++ b/docs/templates/cli-docs.md @@ -0,0 +1,191 @@ +# CLI Command Documentation Template Implementation Plan + +## Overview + +This plan outlines the creation of a standardized template for documenting CLI commands in the Replicated documentation. The template will ensure consistency across all CLI command documentation while following the established style guide principles. + +## Template Structure + +### 1. File Naming Convention +- **Pattern**: `{cli-name}-{command-name}.md` or `{cli-name}-{command-name}.mdx` +- **Examples**: + - `kots-cli-download.md` + - `replicated-cli-app-create.mdx` + - `embedded-cluster-install.mdx` + +### 2. Template Sections + +#### Header Section +- **Command Name**: Use the actual command name as the H1 heading +- **Brief Description**: One-sentence description of what the command does +- **Context/Prerequisites**: When applicable, mention requirements or context + +#### Usage Section +- **Syntax**: Show the exact command syntax with placeholders +- **Parameter Explanations**: Brief explanations of required parameters +- **Global Flags Reference**: Link to global flags when applicable + +#### Flags/Options Section +- **Table Format**: Use consistent table structure for flags +- **Column Headers**: Flag, Type, Description +- **Flag Formatting**: Use backticks around flag names +- **Descriptions**: Clear, concise descriptions following style guide +- **Defaults**: Include default values when applicable +- **Requirements**: Note version requirements or limitations + +#### Examples Section +- **Multiple Use Cases**: Provide practical examples for different scenarios +- **Real Commands**: Use realistic parameter values +- **Comments**: Include explanatory comments when helpful +- **Progressive Complexity**: Start simple, then show advanced usage + +#### Optional Sections +- **Prerequisites**: When specific setup is required +- **Related Commands**: Links to related CLI commands +- **Troubleshooting**: Common issues and solutions +- **See Also**: Cross-references to related documentation + +## Style Guide Adherence + +### Content Guidelines +- **Active Voice**: Use active voice throughout +- **Second Person**: Address the reader as "you" +- **No Marketing Language**: Avoid "simply," "easily," etc. +- **Timeless Language**: Avoid "currently," "new," "now" +- **Concise Descriptions**: Keep descriptions clear and brief + +### Formatting Standards +- **UI Elements**: Bold formatting for UI elements +- **Code Elements**: Backticks for commands, flags, and code +- **Tables**: Use HTML tables for complex flag documentation +- **Lists**: Use bulleted lists for parameter explanations +- **Cross-references**: Follow established linking format + +### Technical Writing Standards +- **Placeholder Text**: Use ALL_CAPS with underscores +- **Parameter Explanations**: Use "Replace X with Y" format +- **Version Requirements**: Clearly note version dependencies +- **Limitations**: Document known limitations prominently + +## Template File Creation + +### Location +- **Primary Location**: `/docs/templates/cli-command.md` +- **Alternative**: Consider both `.md` and `.mdx` versions if needed + +### Template Content Structure +```markdown +# [COMMAND_NAME] + +[Brief description of what the command does and its primary purpose.] + +## Usage + +```bash +[CLI_NAME] [COMMAND_NAME] [REQUIRED_ARGS] [flags] +``` + +* Replace `[REQUIRED_ARGS]` with [description] +* Provide `[flags]` according to the table below + +[Optional: Link to global flags if applicable] + +## Flags + +| Flag | Type | Description | +|:-----|------|-------------| +| `--flag-name` | string | [Description with default if applicable] | +| `-h, --help` | | help for [command] | + +## Examples + +### [Use Case 1] +```bash +[example command] +``` + +### [Use Case 2] +```bash +[example command with explanation] +``` + +## Prerequisites +[If applicable - specific requirements before using this command] + +## Related Commands +[If applicable - links to related CLI commands] + +## See Also +[If applicable - cross-references to related documentation] +``` + +## Implementation Steps + +### Phase 1: Template Creation +1. **Create Base Template**: Develop the standard CLI command template file +2. **Style Guide Integration**: Ensure all elements follow established guidelines +3. **Comment Guidelines**: Add comprehensive comments for template users +4. **Validation**: Review against existing CLI documentation for consistency + +### Phase 2: Documentation Standards +1. **Writing Guidelines**: Create specific guidelines for CLI command documentation +2. **Flag Documentation Standards**: Establish consistent flag description patterns +3. **Example Standards**: Define requirements for example quality and coverage +4. **Cross-reference Standards**: Establish linking patterns for CLI commands + +### Phase 3: Template Variants +1. **Simple Command Template**: For commands with minimal flags +2. **Complex Command Template**: For commands with extensive options +3. **Command Group Template**: For documenting command groups/subcommands +4. **Legacy Command Template**: For deprecated or legacy commands + +### Phase 4: Integration and Training +1. **Template Documentation**: Create documentation on how to use the template +2. **Best Practices Guide**: Develop best practices for CLI documentation +3. **Review Checklist**: Create checklist for CLI command documentation reviews +4. **Style Guide Updates**: Update main style guide with CLI-specific guidance + +## Quality Assurance + +### Content Review Criteria +- **Accuracy**: Command syntax and flag descriptions are correct +- **Completeness**: All flags and options are documented +- **Clarity**: Descriptions are clear and unambiguous +- **Consistency**: Formatting and style match template standards +- **Examples**: Practical, realistic examples are provided + +### Technical Review Criteria +- **Syntax Validation**: Command syntax is accurate +- **Version Compatibility**: Version requirements are clearly noted +- **Link Validation**: All cross-references work correctly +- **Accessibility**: Content follows accessibility guidelines + +## Future Considerations + +### Maintenance +- **Version Updates**: Process for updating commands when CLI tools change +- **Deprecation Handling**: Strategy for documenting deprecated commands +- **Cross-CLI Consistency**: Ensuring consistency across different CLI tools + +### Enhancement Opportunities +- **Interactive Examples**: Consider adding interactive command examples +- **Command Comparison**: Templates for comparing similar commands +- **Troubleshooting Integration**: Built-in troubleshooting sections +- **Auto-generation**: Future automation of CLI documentation generation + +## Success Metrics + +### Consistency Metrics +- All CLI commands follow the same structure +- Flag documentation uses consistent formatting +- Examples follow established patterns + +### Quality Metrics +- Reduced documentation review time +- Fewer clarification questions from users +- Improved user task completion rates + +### Maintenance Metrics +- Faster documentation updates for CLI changes +- Reduced effort for new CLI command documentation +- Consistent cross-references and linking diff --git a/docs/vendor/embedded-disaster-recovery.mdx b/docs/vendor/embedded-disaster-recovery.mdx index db9dbb4019..8e6565af46 100644 --- a/docs/vendor/embedded-disaster-recovery.mdx +++ b/docs/vendor/embedded-disaster-recovery.mdx @@ -44,7 +44,7 @@ Embedded Cluster disaster recovery has the following limitations and known issue * Velero is installed only during the initial installation process. Enabling the disaster recovery license field for customers after they have already installed will not do anything. -* If the `--admin-console-port` flag was used during install to change the port for the Admin Console, note that during a restore the Admin Console port will be used from the backup and cannot be changed. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). +* If the `--admin-console-port` flag was used during install to change the port for the Admin Console, note that during a restore the Admin Console port will be used from the backup and cannot be changed. For more information, see [install](/reference/embedded-cluster-install). ## Configure Disaster Recovery @@ -223,11 +223,11 @@ To restore from a backup: Note the following requirements and guidance for the `restore` command: - * If the installation is behind a proxy, the same proxy settings provided during install must be provided to the restore command using `--http-proxy`, `--https-proxy`, and `--no-proxy`. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). + * If the installation is behind a proxy, the same proxy settings provided during install must be provided to the restore command using `--http-proxy`, `--https-proxy`, and `--no-proxy`. For more information, see [install](/reference/embedded-cluster-install). - * If the `--cidr` flag was used during install to the set IP address ranges for Pods and Services, this flag must be provided with the same CIDR during the restore. If this flag is not provided or is provided with a different CIDR, the restore will fail with an error message telling you to rerun with the appropriate value. However, it will take some time before that error occurs. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). + * If the `--cidr` flag was used during install to the set IP address ranges for Pods and Services, this flag must be provided with the same CIDR during the restore. If this flag is not provided or is provided with a different CIDR, the restore will fail with an error message telling you to rerun with the appropriate value. However, it will take some time before that error occurs. For more information, see [install](/reference/embedded-cluster-install). - * If the `--local-artifact-mirror-port` flag was used during install to change the port for the Local Artifact Mirror (LAM), you can optionally use the `--local-artifact-mirror-port` flag to choose a different LAM port during restore. For example, `restore --local-artifact-mirror-port=50000`. If no LAM port is provided during restore, the LAM port that was supplied during installation will be used. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). + * If the `--local-artifact-mirror-port` flag was used during install to change the port for the Local Artifact Mirror (LAM), you can optionally use the `--local-artifact-mirror-port` flag to choose a different LAM port during restore. For example, `restore --local-artifact-mirror-port=50000`. If no LAM port is provided during restore, the LAM port that was supplied during installation will be used. For more information, see [install](/reference/embedded-cluster-install). You will be guided through the process of restoring from a backup. From 4d3e1f45e0a0de8c02574f70040919e64e5adee0 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 6 Aug 2025 12:05:01 -0600 Subject: [PATCH 3/9] edits --- docs/reference/embedded-cluster-join-print-command.mdx | 2 +- docs/reference/embedded-cluster-join.mdx | 7 ++++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/reference/embedded-cluster-join-print-command.mdx b/docs/reference/embedded-cluster-join-print-command.mdx index 7faa4674d8..c6a0234c8c 100644 --- a/docs/reference/embedded-cluster-join-print-command.mdx +++ b/docs/reference/embedded-cluster-join-print-command.mdx @@ -1,6 +1,6 @@ # join print-command -This topic describes the options available with the Embedded Cluster `join print-command` command. +This topic describes the options available with the Embedded Cluster `join print-command` command. For more information about joining nodes, see [Manage Multi-Node Clusters with Embedded Cluster](/enterprise/embedded-manage-nodes). ## Usage diff --git a/docs/reference/embedded-cluster-join.mdx b/docs/reference/embedded-cluster-join.mdx index a114b46315..1b31c9e80d 100644 --- a/docs/reference/embedded-cluster-join.mdx +++ b/docs/reference/embedded-cluster-join.mdx @@ -1,6 +1,6 @@ # join -This topic describes the options available with the Embedded Cluster `join` command. +This topic describes the options available with the Embedded Cluster `join` command. For more information about joining nodes, see [Manage Multi-Node Clusters with Embedded Cluster](/enterprise/embedded-manage-nodes). ## Usage @@ -79,3 +79,8 @@ sudo ./ join [command] +## Examples + +```bash +sudo ./slackernews join 10.128.0.55:30000 dCH2tsK9xvucAIbME0RBs7z7 +``` \ No newline at end of file From 1f9392d4b0174c8847e10279440f4ee493909267 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 6 Aug 2025 12:06:41 -0600 Subject: [PATCH 4/9] remove 'source content' --- docs/reference/embedded-cluster-restore.mdx | 23 +-------------------- 1 file changed, 1 insertion(+), 22 deletions(-) diff --git a/docs/reference/embedded-cluster-restore.mdx b/docs/reference/embedded-cluster-restore.mdx index da3bd0a970..588faaa111 100644 --- a/docs/reference/embedded-cluster-restore.mdx +++ b/docs/reference/embedded-cluster-restore.mdx @@ -107,25 +107,4 @@ sudo ./ restore [flags]

Assume yes to all prompts.

- - -$ SOURCE CONTENT -Restore a gitea-two cluster - -Usage: - gitea-two restore [flags] - -Flags: - --airgap-bundle string Path to the air gap bundle. If set, the installation will complete without internet access. - --cidr string CIDR block of available private IP addresses (/16 or larger) (default "10.244.0.0/16") - --data-dir string Path to the data directory (default "/var/lib/embedded-cluster") - -h, --help help for restore - --http-proxy string HTTP proxy to use for the installation - --https-proxy string HTTPS proxy to use for the installation - --ignore-host-preflights Allow bypassing host preflight failures - --local-artifact-mirror-port int Port on which the Local Artifact Mirror will be served (default 50000) - --network-interface string The network interface to use for the cluster - --no-proxy string Comma-separated list of hosts for which not to use a proxy - --private-ca strings Path to a trusted private CA certificate file - --skip-store-validation Skip validation of the backup storage location - -y, --yes Assume yes to all prompts. + \ No newline at end of file From d96dd7838bc23699701808da55bba4c2a716af1e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 6 Aug 2025 12:10:24 -0600 Subject: [PATCH 5/9] add relevant links --- docs/reference/embedded-cluster-support-bundle.mdx | 2 +- docs/reference/embedded-cluster-update.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/embedded-cluster-support-bundle.mdx b/docs/reference/embedded-cluster-support-bundle.mdx index ec99880c70..5eba094dc4 100644 --- a/docs/reference/embedded-cluster-support-bundle.mdx +++ b/docs/reference/embedded-cluster-support-bundle.mdx @@ -1,6 +1,6 @@ # support-bundle -This topic describes the options available with the Embedded Cluster `support-bundle` command. +This topic describes the options available with the Embedded Cluster `support-bundle` command. For more information about generating support bundles for Embedded Cluster installations, see [Troubleshoot Embedded Cluster](/vendor/embedded-troubleshooting). ## Usage diff --git a/docs/reference/embedded-cluster-update.mdx b/docs/reference/embedded-cluster-update.mdx index 1b07a50035..f4e7187bd7 100644 --- a/docs/reference/embedded-cluster-update.mdx +++ b/docs/reference/embedded-cluster-update.mdx @@ -1,6 +1,6 @@ # update -This topic describes the options available with the Embedded Cluster `update` command. +This topic describes the options available with the Embedded Cluster `update` command. For more information about performing updates with Embedded Cluster, see [Perform Updates in Embedded Clusters](/enterprise/updating-embedded). ## Usage From 914cb72564aa54ee0dd8897bbf59026de5c3aaf4 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 6 Aug 2025 12:15:10 -0600 Subject: [PATCH 6/9] rm tempalte --- docs/templates/cli-docs.md | 191 ------------------------------------- 1 file changed, 191 deletions(-) delete mode 100644 docs/templates/cli-docs.md diff --git a/docs/templates/cli-docs.md b/docs/templates/cli-docs.md deleted file mode 100644 index ade3dd28b3..0000000000 --- a/docs/templates/cli-docs.md +++ /dev/null @@ -1,191 +0,0 @@ -# CLI Command Documentation Template Implementation Plan - -## Overview - -This plan outlines the creation of a standardized template for documenting CLI commands in the Replicated documentation. The template will ensure consistency across all CLI command documentation while following the established style guide principles. - -## Template Structure - -### 1. File Naming Convention -- **Pattern**: `{cli-name}-{command-name}.md` or `{cli-name}-{command-name}.mdx` -- **Examples**: - - `kots-cli-download.md` - - `replicated-cli-app-create.mdx` - - `embedded-cluster-install.mdx` - -### 2. Template Sections - -#### Header Section -- **Command Name**: Use the actual command name as the H1 heading -- **Brief Description**: One-sentence description of what the command does -- **Context/Prerequisites**: When applicable, mention requirements or context - -#### Usage Section -- **Syntax**: Show the exact command syntax with placeholders -- **Parameter Explanations**: Brief explanations of required parameters -- **Global Flags Reference**: Link to global flags when applicable - -#### Flags/Options Section -- **Table Format**: Use consistent table structure for flags -- **Column Headers**: Flag, Type, Description -- **Flag Formatting**: Use backticks around flag names -- **Descriptions**: Clear, concise descriptions following style guide -- **Defaults**: Include default values when applicable -- **Requirements**: Note version requirements or limitations - -#### Examples Section -- **Multiple Use Cases**: Provide practical examples for different scenarios -- **Real Commands**: Use realistic parameter values -- **Comments**: Include explanatory comments when helpful -- **Progressive Complexity**: Start simple, then show advanced usage - -#### Optional Sections -- **Prerequisites**: When specific setup is required -- **Related Commands**: Links to related CLI commands -- **Troubleshooting**: Common issues and solutions -- **See Also**: Cross-references to related documentation - -## Style Guide Adherence - -### Content Guidelines -- **Active Voice**: Use active voice throughout -- **Second Person**: Address the reader as "you" -- **No Marketing Language**: Avoid "simply," "easily," etc. -- **Timeless Language**: Avoid "currently," "new," "now" -- **Concise Descriptions**: Keep descriptions clear and brief - -### Formatting Standards -- **UI Elements**: Bold formatting for UI elements -- **Code Elements**: Backticks for commands, flags, and code -- **Tables**: Use HTML tables for complex flag documentation -- **Lists**: Use bulleted lists for parameter explanations -- **Cross-references**: Follow established linking format - -### Technical Writing Standards -- **Placeholder Text**: Use ALL_CAPS with underscores -- **Parameter Explanations**: Use "Replace X with Y" format -- **Version Requirements**: Clearly note version dependencies -- **Limitations**: Document known limitations prominently - -## Template File Creation - -### Location -- **Primary Location**: `/docs/templates/cli-command.md` -- **Alternative**: Consider both `.md` and `.mdx` versions if needed - -### Template Content Structure -```markdown -# [COMMAND_NAME] - -[Brief description of what the command does and its primary purpose.] - -## Usage - -```bash -[CLI_NAME] [COMMAND_NAME] [REQUIRED_ARGS] [flags] -``` - -* Replace `[REQUIRED_ARGS]` with [description] -* Provide `[flags]` according to the table below - -[Optional: Link to global flags if applicable] - -## Flags - -| Flag | Type | Description | -|:-----|------|-------------| -| `--flag-name` | string | [Description with default if applicable] | -| `-h, --help` | | help for [command] | - -## Examples - -### [Use Case 1] -```bash -[example command] -``` - -### [Use Case 2] -```bash -[example command with explanation] -``` - -## Prerequisites -[If applicable - specific requirements before using this command] - -## Related Commands -[If applicable - links to related CLI commands] - -## See Also -[If applicable - cross-references to related documentation] -``` - -## Implementation Steps - -### Phase 1: Template Creation -1. **Create Base Template**: Develop the standard CLI command template file -2. **Style Guide Integration**: Ensure all elements follow established guidelines -3. **Comment Guidelines**: Add comprehensive comments for template users -4. **Validation**: Review against existing CLI documentation for consistency - -### Phase 2: Documentation Standards -1. **Writing Guidelines**: Create specific guidelines for CLI command documentation -2. **Flag Documentation Standards**: Establish consistent flag description patterns -3. **Example Standards**: Define requirements for example quality and coverage -4. **Cross-reference Standards**: Establish linking patterns for CLI commands - -### Phase 3: Template Variants -1. **Simple Command Template**: For commands with minimal flags -2. **Complex Command Template**: For commands with extensive options -3. **Command Group Template**: For documenting command groups/subcommands -4. **Legacy Command Template**: For deprecated or legacy commands - -### Phase 4: Integration and Training -1. **Template Documentation**: Create documentation on how to use the template -2. **Best Practices Guide**: Develop best practices for CLI documentation -3. **Review Checklist**: Create checklist for CLI command documentation reviews -4. **Style Guide Updates**: Update main style guide with CLI-specific guidance - -## Quality Assurance - -### Content Review Criteria -- **Accuracy**: Command syntax and flag descriptions are correct -- **Completeness**: All flags and options are documented -- **Clarity**: Descriptions are clear and unambiguous -- **Consistency**: Formatting and style match template standards -- **Examples**: Practical, realistic examples are provided - -### Technical Review Criteria -- **Syntax Validation**: Command syntax is accurate -- **Version Compatibility**: Version requirements are clearly noted -- **Link Validation**: All cross-references work correctly -- **Accessibility**: Content follows accessibility guidelines - -## Future Considerations - -### Maintenance -- **Version Updates**: Process for updating commands when CLI tools change -- **Deprecation Handling**: Strategy for documenting deprecated commands -- **Cross-CLI Consistency**: Ensuring consistency across different CLI tools - -### Enhancement Opportunities -- **Interactive Examples**: Consider adding interactive command examples -- **Command Comparison**: Templates for comparing similar commands -- **Troubleshooting Integration**: Built-in troubleshooting sections -- **Auto-generation**: Future automation of CLI documentation generation - -## Success Metrics - -### Consistency Metrics -- All CLI commands follow the same structure -- Flag documentation uses consistent formatting -- Examples follow established patterns - -### Quality Metrics -- Reduced documentation review time -- Fewer clarification questions from users -- Improved user task completion rates - -### Maintenance Metrics -- Faster documentation updates for CLI changes -- Reduced effort for new CLI command documentation -- Consistent cross-references and linking From c890b19789fa5f314c645021cad3c889b22dfc62 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Aug 2025 09:07:08 -0600 Subject: [PATCH 7/9] change heading to subcommands --- docs/reference/embedded-cluster-admin-console.mdx | 2 +- docs/reference/embedded-cluster-completion.mdx | 2 +- docs/reference/embedded-cluster-join-print-command.mdx | 2 +- docs/reference/embedded-cluster-join.mdx | 2 +- docs/reference/embedded-cluster-version.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/embedded-cluster-admin-console.mdx b/docs/reference/embedded-cluster-admin-console.mdx index fab184b82d..4ab53d9271 100644 --- a/docs/reference/embedded-cluster-admin-console.mdx +++ b/docs/reference/embedded-cluster-admin-console.mdx @@ -8,7 +8,7 @@ This topic describes the options available with the Embedded Cluster `admin-cons sudo ./ admin-console reset-password [flags] ``` -## Commands +## Subcommands diff --git a/docs/reference/embedded-cluster-completion.mdx b/docs/reference/embedded-cluster-completion.mdx index f5cceeb3c9..de2338598a 100644 --- a/docs/reference/embedded-cluster-completion.mdx +++ b/docs/reference/embedded-cluster-completion.mdx @@ -8,7 +8,7 @@ This topic describes the options available with the Embedded Cluster `completion sudo ./ completion [command] ``` -## Commands +## Subcommands
diff --git a/docs/reference/embedded-cluster-join-print-command.mdx b/docs/reference/embedded-cluster-join-print-command.mdx index c6a0234c8c..4454deed00 100644 --- a/docs/reference/embedded-cluster-join-print-command.mdx +++ b/docs/reference/embedded-cluster-join-print-command.mdx @@ -8,7 +8,7 @@ This topic describes the options available with the Embedded Cluster `join print sudo ./ join print-command [flags] ``` -## Commands +## Subcommands
diff --git a/docs/reference/embedded-cluster-join.mdx b/docs/reference/embedded-cluster-join.mdx index 1b31c9e80d..354a5c9826 100644 --- a/docs/reference/embedded-cluster-join.mdx +++ b/docs/reference/embedded-cluster-join.mdx @@ -12,7 +12,7 @@ sudo ./ join [flags] sudo ./ join [command] ``` -## Commands +## Subcommands
diff --git a/docs/reference/embedded-cluster-version.mdx b/docs/reference/embedded-cluster-version.mdx index b8949a4584..d1019f33ba 100644 --- a/docs/reference/embedded-cluster-version.mdx +++ b/docs/reference/embedded-cluster-version.mdx @@ -12,7 +12,7 @@ sudo ./ version [flags] sudo ./ version [command] ``` -## Commands +## Subcommands
From 641f06466fed0f185464a2f0c9092e2a6c27c9ab Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Aug 2025 09:08:00 -0600 Subject: [PATCH 8/9] remove subcommands for print --- .../embedded-cluster-join-print-command.mdx | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/docs/reference/embedded-cluster-join-print-command.mdx b/docs/reference/embedded-cluster-join-print-command.mdx index 4454deed00..fbf003489b 100644 --- a/docs/reference/embedded-cluster-join-print-command.mdx +++ b/docs/reference/embedded-cluster-join-print-command.mdx @@ -8,21 +8,6 @@ This topic describes the options available with the Embedded Cluster `join print sudo ./ join print-command [flags] ``` -## Subcommands - -
- - - - - - - - -
CommandDescription
run-preflights -

Run join host preflights for the application.

-
- ## Flags From a3af4a674049871ff44bebafe4c4346bdcec6a1b Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Aug 2025 09:12:38 -0600 Subject: [PATCH 9/9] edit intro for update command --- docs/reference/embedded-cluster-update.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/embedded-cluster-update.mdx b/docs/reference/embedded-cluster-update.mdx index f4e7187bd7..6fc8474972 100644 --- a/docs/reference/embedded-cluster-update.mdx +++ b/docs/reference/embedded-cluster-update.mdx @@ -1,11 +1,11 @@ # update -This topic describes the options available with the Embedded Cluster `update` command. For more information about performing updates with Embedded Cluster, see [Perform Updates in Embedded Clusters](/enterprise/updating-embedded). +This topic describes the options available with the Embedded Cluster `update` command. The `update` command allows you to update an instance with a new air gap bundle. This is part of the process for performing updates in air-gapped environments. For more information, see [Update in Air Gap Clusters](/enterprise/updating-embedded#update-in-air-gap-clusters) in _Perform Updates in Embedded Clusters_. ## Usage ```bash -sudo ./ update [flags] +sudo ./ update. --airgap-bundle [flags] ``` ## Flags