From 24e6b2cd34b485d924f54a3a89367e3cc147ff9c Mon Sep 17 00:00:00 2001 From: Noah Campbell Date: Wed, 22 Oct 2025 17:56:47 -0500 Subject: [PATCH 1/7] replicaed cli profile and .replicated docs --- docs/reference/cli-profiles.md | 179 +++++++ docs/reference/cli-replicated-config.md | 444 ++++++++++++++++++ docs/reference/replicated-cli-installing.mdx | 12 +- .../reference/replicated-cli-release-lint.mdx | 7 +- docs/vendor/quick-start.mdx | 8 + docs/vendor/releases-creating-cli.mdx | 10 +- docs/vendor/replicated-api-tokens.md | 12 + docs/vendor/tutorial-helm-cli.mdx | 4 + sidebars.js | 2 + 9 files changed, 674 insertions(+), 4 deletions(-) create mode 100644 docs/reference/cli-profiles.md create mode 100644 docs/reference/cli-replicated-config.md diff --git a/docs/reference/cli-profiles.md b/docs/reference/cli-profiles.md new file mode 100644 index 0000000000..dfeab189ab --- /dev/null +++ b/docs/reference/cli-profiles.md @@ -0,0 +1,179 @@ +# CLI Authentication Profiles + +The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials easily. This is useful when working with multiple Replicated accounts or environments. + +## Overview + +Authentication profiles store your API token and optionally custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). + +### Authentication Priority + +The CLI determines which credentials to use in the following order: + +1. `REPLICATED_API_TOKEN` environment variable (highest priority) +2. `--profile` flag (per-command override) +3. Default profile from `~/.replicated/config.yaml` +4. Legacy single token (backward compatibility) + +## Commands + +### `replicated profile add [profile-name]` + +Add a new authentication profile with the specified name. + +**Flags:** +- `--token` - API token for this profile (optional, will prompt if not provided). Supports environment variable expansion using `$VAR` or `${VAR}` syntax. + +**Examples:** + +```bash +# Add a production profile (will prompt for token) +replicated profile add prod + +# Add a production profile with token flag +replicated profile add prod --token=your-prod-token + +# Add a profile using an existing environment variable +replicated profile add prod --token='$REPLICATED_API_TOKEN' +``` + +If a profile with the same name already exists, it will be updated. If you add the first profile or if no default profile is set, the newly added profile will automatically become the default. + +**Note:** When using environment variables, make sure to quote the value (e.g., `'$REPLICATED_API_TOKEN'`) to prevent shell expansion and allow the CLI to expand it instead. + +### `replicated profile ls` + +List all authentication profiles. + +**Examples:** + +```bash +replicated profile ls +``` + +**Output:** + +``` + DEFAULT NAME API ORIGIN REGISTRY ORIGIN + * prod + dev +``` + +The asterisk (*) in the DEFAULT column indicates which profile is currently set as default. + +### `replicated profile use [profile-name]` + +Set the default authentication profile. + +**Examples:** + +```bash +replicated profile use prod +``` + +This command sets the specified profile as the default for all CLI operations. You can override the default on a per-command basis using the `--profile` flag. + +### `replicated profile edit [profile-name]` + +Edit an existing authentication profile. Only the flags you provide will be updated; other fields will remain unchanged. + +**Flags:** +- `--token` - New API token for this profile (optional). Supports environment variable expansion using `$VAR` or `${VAR}` syntax. + +**Examples:** + +```bash +# Update the token for a profile +replicated profile edit dev --token=new-dev-token + +# Update a profile using an environment variable +replicated profile edit dev --token='$REPLICATED_API_TOKEN' +``` + +### `replicated profile rm [profile-name]` + +Remove an authentication profile. + +**Examples:** + +```bash +replicated profile rm dev +``` + +If you remove the default profile and other profiles exist, one of the remaining profiles will be automatically set as the default. + +### `replicated profile set-default [profile-name]` + +Set the default authentication profile. This is an alias for `replicated profile use`. + +**Examples:** + +```bash +replicated profile set-default prod +``` + +## Usage Examples + +### Basic Workflow + +```bash +# Add a production profile using an existing environment variable +replicated profile add prod --token='$REPLICATED_API_TOKEN' + +# Add a development profile with a direct token +replicated profile add dev --token=your-dev-token + +# List all profiles +replicated profile ls + +# Switch to production profile +replicated profile use prod + +# Use development profile for a single command +replicated app ls --profile=dev + +# Edit a profile's token +replicated profile edit dev --token=new-dev-token + +# Remove a profile +replicated profile rm dev +``` + +### Working with Multiple Accounts + +```bash +# Add profiles for different accounts +replicated profile add company-a --token=token-a +replicated profile add company-b --token=token-b + +# Switch between accounts +replicated profile use company-a +replicated app ls # Lists apps for company-a + +replicated profile use company-b +replicated app ls # Lists apps for company-b +``` + +## Security + +- All credentials are stored in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only) +- Tokens are masked when prompted interactively +- Environment variables take precedence, allowing temporary overrides without modifying stored profiles + +## Troubleshooting + +### Profile Not Found + +If you see "profile not found", use `replicated profile ls` to list available profiles and verify the profile name. + +### Permission Denied + +If you encounter permission issues with `~/.replicated/config.yaml`, verify the file has the correct permissions: + +```bash +chmod 600 ~/.replicated/config.yaml +``` + +### Multiple Profiles, Wrong One Being Used + +Check the default profile with `replicated profile ls` and ensure the correct profile is marked with an asterisk (*). You can change the default with `replicated profile use [profile-name]`. diff --git a/docs/reference/cli-replicated-config.md b/docs/reference/cli-replicated-config.md new file mode 100644 index 0000000000..67aaccf492 --- /dev/null +++ b/docs/reference/cli-replicated-config.md @@ -0,0 +1,444 @@ +# .replicated Configuration File + +The `.replicated` configuration file is used to define your project structure, resource locations, and linting preferences for the Replicated CLI. This file enables commands like `replicated release create` and `replicated release lint` to automatically discover and process your application resources. + +## File Location + +The CLI searches for `.replicated` or `.replicated.yaml` starting from the current directory and walking up the directory tree. This supports both: +- Single-repository projects with one `.replicated` file at the root +- Monorepo projects with multiple `.replicated` files at different levels (configs are merged) + +## Creating a Configuration File + +### Using `replicated config init` + +The easiest way to create a `.replicated` file is using the interactive `init` command: + +```bash +# Interactive mode with prompts +replicated config init + +# Skip auto-detection +replicated config init --skip-detection +``` + +The `init` command will: +1. Auto-detect Helm charts, preflight specs, and support bundles in your project +2. Prompt for application configuration (app ID/slug) +3. Guide you through linting setup +4. Generate a `.replicated` file with your selections + +### Manual Creation + +You can also create a `.replicated` file manually using YAML format. + +## Configuration Structure + +Here's a complete example with all available fields: + +```yaml +# Application identification +appId: "" # Your application ID (optional) +appSlug: "" # Your application slug (optional, more commonly used) + +# Automatic promotion channels +promoteToChannelIds: [] # List of channel IDs to promote to +promoteToChannelNames: [] # List of channel names to promote to (e.g., ["beta", "stable"]) + +# Helm charts +charts: + - path: "./helm-chart" # Path or glob pattern to chart directory + chartVersion: "" # Override chart version (optional) + appVersion: "" # Override app version (optional) + +# Preflight checks +preflights: + - path: "./preflights/**" # Path or glob pattern to preflight specs + valuesPath: "./helm-chart" # Path to helm chart for template rendering (required for v1beta3 preflights) + +# Kubernetes manifests and support bundles +manifests: ["./support-bundles/**"] # Glob patterns for manifest files + +# Release labeling +releaseLabel: "" # Label pattern for releases (e.g., "v{{.Semver}}") + +# Linting configuration +repl-lint: + version: 1 + linters: + helm: + disabled: false # Enable/disable Helm linting + preflight: + disabled: false # Enable/disable preflight linting + support-bundle: + disabled: false # Enable/disable support bundle linting + tools: + helm: "latest" # Helm version (semantic version or "latest") + preflight: "latest" # Preflight version (semantic version or "latest") + support-bundle: "latest" # Support bundle version (semantic version or "latest") +``` + +## Field Reference + +### Application Fields + +#### `appId` (string, optional) +Your Replicated application ID. You can find this in the Vendor Portal at vendor.replicated.com. + +#### `appSlug` (string, optional) +Your Replicated application slug. This is the human-readable identifier for your app (more commonly used than `appId`). + +**Example:** +```yaml +appSlug: "my-application" +``` + +### Release Configuration + +#### `promoteToChannelIds` (array of strings, optional) +List of channel IDs to automatically promote releases to when using `replicated release create`. + +#### `promoteToChannelNames` (array of strings, optional) +List of channel names to automatically promote releases to. More convenient than using IDs. + +**Example:** +```yaml +promoteToChannelNames: ["beta", "stable"] +``` + +#### `releaseLabel` (string, optional) +Template string for release labels. Supports Go template syntax. + +**Example:** +```yaml +releaseLabel: "v{{.Semver}}" +``` + +### Resource Configuration + +#### `charts` (array of objects, optional) +Helm charts to include in releases and lint operations. + +**Fields:** +- `path` (string, required): Path or glob pattern to chart directory (e.g., `./chart` or `./charts/*`) +- `chartVersion` (string, optional): Override the chart version +- `appVersion` (string, optional): Override the app version + +**Example:** +```yaml +charts: + - path: "./helm-chart" + - path: "./charts/app-*" # Glob patterns supported + chartVersion: "1.2.3" +``` + +#### `preflights` (array of objects, optional) +Preflight check specifications to validate before installation. + +**Fields:** +- `path` (string, required): Path or glob pattern to preflight spec files +- `valuesPath` (string, optional but recommended): Path to Helm chart directory for template rendering. Required for v1beta3 preflights that use templating. + +**Example:** +```yaml +preflights: + - path: "./preflights/preflight.yaml" + valuesPath: "./helm-chart" # Chart directory for rendering templates + - path: "./preflights/**/*.yaml" # Glob pattern + valuesPath: "./helm-chart" +``` + +#### `manifests` (array of strings, optional) +Glob patterns for Kubernetes manifest files, including support bundle specs. These are searched for support bundle specifications during linting. + +**Example:** +```yaml +manifests: + - "./manifests/**/*.yaml" + - "./support-bundles/**" +``` + +### Linting Configuration + +#### `repl-lint` (object, optional) +Configuration for the linting subsystem. + +**Fields:** +- `version` (integer): Configuration version (currently `1`) +- `linters` (object): Enable/disable specific linters +- `tools` (map): Tool versions to use + +**Example:** +```yaml +repl-lint: + version: 1 + linters: + helm: + disabled: false # Enable Helm linting + preflight: + disabled: false # Enable preflight linting + support-bundle: + disabled: false # Enable support bundle linting + embedded-cluster: + disabled: true # Disable embedded cluster linting + kots: + disabled: true # Disable KOTS linting + tools: + helm: "3.14.4" # Specific version + preflight: "latest" # Use latest version + support-bundle: "0.123.9" +``` + +### Linter Configuration + +Each linter under `repl-lint.linters` supports: +- `disabled` (boolean): Set to `true` to disable the linter, `false` or omit to enable + +**Available linters:** +- `helm`: Validates Helm chart syntax and best practices +- `preflight`: Validates preflight specification syntax +- `support-bundle`: Validates support bundle specification syntax +- `embedded-cluster`: Validates embedded cluster configurations (disabled by default) +- `kots`: Validates KOTS manifests (disabled by default) + +### Tool Versions + +The `tools` map specifies which versions of linting tools to use: + +- `helm`: Helm CLI version for chart validation +- `preflight`: Preflight CLI version for preflight spec validation +- `support-bundle`: Support Bundle CLI version for support bundle validation + +**Version formats:** +- `"latest"`: Automatically fetch the latest stable version from GitHub +- Semantic version: Specific version (e.g., `"3.14.4"`, `"v0.123.9"`) + +**Example:** +```yaml +tools: + helm: "latest" # Always use latest Helm + preflight: "0.123.9" # Pin preflight to specific version + support-bundle: "latest" +``` + +## Path Resolution + +### Relative Paths +All paths in the configuration file are resolved relative to the directory containing the `.replicated` file. This ensures commands work correctly regardless of where they're invoked. + +### Glob Patterns +Paths support glob patterns for flexible resource discovery: +- `*`: Matches any characters except `/` +- `**`: Matches any characters including `/` (recursive) +- `?`: Matches any single character +- `[abc]`: Matches any character in brackets +- `{a,b}`: Matches any of the comma-separated patterns + +**Examples:** +```yaml +charts: + - path: "./charts/*" # All immediate subdirectories + - path: "./services/**/chart" # Any chart directory under services + +preflights: + - path: "./checks/**/*.yaml" # All YAML files recursively + +manifests: + - "./*/manifests/**" # Manifests in any top-level directory +``` + +## Monorepo Support + +For monorepo projects, you can have multiple `.replicated` files at different directory levels. The CLI will: +1. Find all `.replicated` files from the current directory up to the root +2. Merge them with child configurations taking precedence +3. Accumulate resources (charts, preflights, manifests) from all levels +4. Override scalar fields (appId, appSlug) with child values + +**Example structure:** +``` +monorepo/ +├── .replicated # Root config with shared settings +│ └── appSlug: "company-suite" +├── service-a/ +│ ├── .replicated # Service A specific config +│ │ └── charts: ["./chart"] +│ └── chart/ +└── service-b/ + ├── .replicated # Service B specific config + │ └── charts: ["./helm"] + └── helm/ +``` + +When running from `monorepo/service-a/`, both configs are merged: +- `appSlug` from root is used (unless overridden in child) +- Charts from both configs are included +- Lint settings are merged with child taking precedence + +## Auto-Discovery Mode + +If no `.replicated` file is found, the CLI operates in auto-discovery mode: +- Automatically searches for Helm charts in the current directory +- Auto-detects preflight specs (files with `kind: Preflight`) +- Auto-detects support bundle specs (files with `kind: SupportBundle`) +- Uses default linting configuration + +This allows quick testing without configuration, but creating a `.replicated` file is recommended for consistent builds. + +## Examples + +### Simple Single-Chart Project + +```yaml +appSlug: "my-application" + +charts: + - path: "./chart" + +manifests: + - "./manifests/**/*.yaml" + +repl-lint: + version: 1 + linters: + helm: + disabled: false + tools: + helm: "latest" +``` + +### Multi-Chart with Preflights + +```yaml +appSlug: "complex-app" +promoteToChannelNames: ["beta"] + +charts: + - path: "./charts/frontend" + - path: "./charts/backend" + - path: "./charts/database" + +preflights: + - path: "./preflights/infrastructure.yaml" + valuesPath: "./charts/backend" + - path: "./preflights/networking.yaml" + valuesPath: "./charts/frontend" + +manifests: + - "./support-bundles/**" + +repl-lint: + version: 1 + linters: + helm: + disabled: false + preflight: + disabled: false + support-bundle: + disabled: false + tools: + helm: "3.14.4" + preflight: "latest" + support-bundle: "latest" +``` + +### Monorepo Service Configuration + +```yaml +# Parent .replicated at monorepo root +appSlug: "enterprise-platform" +promoteToChannelNames: ["stable"] + +repl-lint: + version: 1 + linters: + helm: + disabled: false + preflight: + disabled: false + tools: + helm: "latest" + preflight: "latest" +``` + +```yaml +# Child .replicated in services/auth/ +charts: + - path: "./chart" + +preflights: + - path: "./preflights/*.yaml" + valuesPath: "./chart" +``` + +### Minimal Configuration + +```yaml +# Minimal config - relies on auto-detection +appSlug: "simple-app" +``` + +## Usage with CLI Commands + +### Linting +```bash +# Lint all resources defined in .replicated +replicated release lint + +# With verbose output (shows discovered images) +replicated release lint --verbose + +# JSON output +replicated release lint --output json +``` + +### Creating Releases +```bash +# Create release with resources from .replicated +replicated release create --auto + +# Create and automatically promote to channels from config +replicated release create --auto --promote +``` + +### Initialization +```bash +# Interactive setup +replicated config init +``` + +## Best Practices + +1. **Version Control**: Always commit `.replicated` to version control +2. **Use Glob Patterns**: Leverage globs for flexible resource discovery +3. **Pin Tool Versions**: Use specific versions in CI/CD for reproducible builds +4. **Document Custom Paths**: Add comments for non-standard path structures +5. **Start Simple**: Begin with minimal config and expand as needed +6. **Test Locally**: Run `replicated release lint` before committing +7. **Monorepo Organization**: Use parent configs for shared settings, child configs for service-specific resources + +## Troubleshooting + +### Config Not Found +If the CLI can't find your `.replicated` file: +- Ensure it's named `.replicated` or `.replicated.yaml` +- Check that it's in the current directory or a parent directory +- Verify file permissions (should be readable) + +### Invalid Glob Patterns +If you see glob pattern errors: +- Ensure patterns use valid glob syntax +- Test patterns with `ls` or `find` commands first +- Quote patterns in shell commands to prevent shell expansion + +### Tool Version Errors +If tool version resolution fails: +- Use `"latest"` for automatic version detection +- Specify semantic versions without `v` prefix (e.g., `"3.14.4"`) +- Check internet connectivity for latest version fetching + +### Merge Conflicts in Monorepos +If resource merging isn't working as expected: +- Check file paths are relative to each config file +- Verify both configs are valid YAML +- Use `--debug` flag to see merge details diff --git a/docs/reference/replicated-cli-installing.mdx b/docs/reference/replicated-cli-installing.mdx index 0c1a3ed3d1..a645f08d13 100644 --- a/docs/reference/replicated-cli-installing.mdx +++ b/docs/reference/replicated-cli-installing.mdx @@ -76,9 +76,13 @@ The Replicated CLI supports setting the following environment variables: * To use Replicated CLI commands as part of automation (such as from continuous integration and continuous delivery pipelines), authenticate by providing the `REPLICATED_API_TOKEN` environment variable. * To authorize the Replicated CLI when installing and running the CLI in Docker containers. - + * Optionally set the `REPLICATED_API_TOKEN` environment variable instead of using the `replicated login` command to authorize the Replicated CLI in MacOS or Linux environments. + :::note + The `REPLICATED_API_TOKEN` environment variable takes precedence over authentication profiles. For more information about authentication profiles, see [CLI Authentication Profiles](/reference/cli-profiles). + ::: + * **`REPLICATED_APP`**: The slug of the target application. When using the Replicated CLI to manage applications through your vendor account (including channels, releases, customers, or other objects associated with an application), you can set the `REPLICATED_APP` environment variable to avoid passing the application slug with each command. @@ -142,3 +146,9 @@ To set the `REPLICATED_APP` environment variable: -e REPLICATED_APP=%APP_SLUG% \ replicated/vendor-cli --help ``` + +## Manage Authentication with Profiles + +The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials easily. This is useful when working with multiple Replicated accounts or environments. + +For complete information about authentication profiles, including how to create, manage, and switch between profiles, see [CLI Authentication Profiles](/reference/cli-profiles). diff --git a/docs/reference/replicated-cli-release-lint.mdx b/docs/reference/replicated-cli-release-lint.mdx index 0cf05e7175..9e4bd242d5 100644 --- a/docs/reference/replicated-cli-release-lint.mdx +++ b/docs/reference/replicated-cli-release-lint.mdx @@ -4,7 +4,9 @@ Lint a directory of KOTS manifests ### Synopsis -Lint a directory of KOTS manifests +Lint a directory of KOTS manifests. If a `.replicated` configuration file is present, the command will automatically discover and lint resources based on the configuration. Otherwise, use `--yaml-dir` to specify the directory containing manifest files. + +For more information about configuring automatic resource discovery, see [.replicated Configuration File](/reference/cli-replicated-config). ``` replicated release lint [flags] @@ -16,7 +18,8 @@ replicated release lint [flags] --fail-on string The minimum severity to cause the command to exit with a non-zero exit code. Supported values are [info, warn, error, none]. (default "error") -h, --help help for lint -o, --output string The output format to use. One of: json|table (default "table") - --yaml-dir yaml The directory containing multiple yamls for a Kots release. Cannot be used with the yaml flag. + --verbose Show verbose output, including discovered images + --yaml-dir yaml The directory containing multiple yamls for a Kots release. Cannot be used with the yaml flag. If omitted and a .replicated config exists, resources will be auto-discovered. ``` ### Options inherited from parent commands diff --git a/docs/vendor/quick-start.mdx b/docs/vendor/quick-start.mdx index 96670ab93f..5c08347c5e 100644 --- a/docs/vendor/quick-start.mdx +++ b/docs/vendor/quick-start.mdx @@ -90,6 +90,10 @@ Before you begin, do the following to set up your environment: ``` In the browser window that opens, follow the prompt to log in to your Vendor Portal account and authorize the CLI. + :::tip + The CLI also supports multiple authentication profiles for managing different accounts. See [CLI Authentication Profiles](/reference/cli-profiles). + ::: + 1. Create an application named `SlackerNews`: ```bash @@ -546,6 +550,10 @@ Before you begin, do the following to set up your environment: :::note If you see a `helm-archive-missing` error, confirm that you have only one chart archive in `manifests` for version 1.0.1, and that the `chartVersion` in the HelmChart resource is also set to `1.0.1`. If you notice that any of the errors are from files in your `.history/` directory, run `rm -rf .history` and then lint the files again. ::: + + :::tip + For automated workflows, you can create a `.replicated` configuration file to define your project structure, resources, and linting preferences. This enables commands like `replicated release lint` to automatically discover and process resources without the `--yaml-dir` flag. See [.replicated Configuration File](/reference/cli-replicated-config). + ::: 1. Create and promote a new release, setting the version label of the release to `0.0.2`: diff --git a/docs/vendor/releases-creating-cli.mdx b/docs/vendor/releases-creating-cli.mdx index 3d82ffeed9..f6c53299c2 100644 --- a/docs/vendor/releases-creating-cli.mdx +++ b/docs/vendor/releases-creating-cli.mdx @@ -6,6 +6,10 @@ For information about creating and managing releases with the Vendor Portal, see For information about creating and managing releases with the Vendor API v3, see the [releases](https://replicated-vendor-api.readme.io/reference/createrelease) section in the Vendor API v3 documentation. +:::tip +You can use a `.replicated` configuration file to define your project structure and resource locations. See [.replicated Configuration File](/reference/cli-replicated-config). +::: + ## Prerequisites Before you create a release using the Replicated CLI, complete the following prerequisites: @@ -50,13 +54,17 @@ To create and promote a release: 1. In the same directory that contains the release files, add a HelmChart custom resource for each Helm chart in the release. See [Configuring the HelmChart Custom Resource](helm-native-v2-using). 1. Lint the application manifest files and ensure that there are no errors in the YAML: - + ```bash replicated release lint --yaml-dir=PATH_TO_RELEASE_DIR ``` Where `PATH_TO_RELEASE_DIR` is the path to the directory with the release files. + :::note + If you have a `.replicated` configuration file, you can run `replicated release lint` without the `--yaml-dir` flag to automatically discover and lint resources. See [.replicated Configuration File](/reference/cli-replicated-config). + ::: + For more information, see [release lint](/reference/replicated-cli-release-lint) and [Linter Rules](/reference/linter). 1. Do one of the following: diff --git a/docs/vendor/replicated-api-tokens.md b/docs/vendor/replicated-api-tokens.md index cd44785175..2bd58faa7e 100644 --- a/docs/vendor/replicated-api-tokens.md +++ b/docs/vendor/replicated-api-tokens.md @@ -10,6 +10,10 @@ The Vendor API v3 is the API that manages applications in the Replicated Vendor Using the Replicated CLI and Vendor API V3 requires an API token for authorization. Tokens are primarily used for automated customer, channel, and release management. You create tokens in the Vendor Portal. +:::tip +The Replicated CLI supports multiple authentication profiles for managing tokens across different accounts or environments. See [CLI Authentication Profiles](/reference/cli-profiles). +::: + The following types of tokens are available: - [Service Accounts](#service-accounts) @@ -64,6 +68,10 @@ To generate a service account: 1. Copy the service account token and save it in a secure location. The token will not be available to view again. + :::tip + You can store this token in a CLI authentication profile for easy management. See [CLI Authentication Profiles](/reference/cli-profiles). + ::: + :::note To remove a service account, select **Remove** for the service account that you want to delete. ::: @@ -93,6 +101,10 @@ To generate a user API token: 1. Copy the user API token that displays and save it in a secure location. The token will not be available to view again. + :::tip + You can store this token in a CLI authentication profile for easy management. See [CLI Authentication Profiles](/reference/cli-profiles). + ::: + :::note To revoke a token, select **Revoke token** for the token that you want to delete. ::: diff --git a/docs/vendor/tutorial-helm-cli.mdx b/docs/vendor/tutorial-helm-cli.mdx index dce730ec09..d7087de0d1 100644 --- a/docs/vendor/tutorial-helm-cli.mdx +++ b/docs/vendor/tutorial-helm-cli.mdx @@ -113,6 +113,10 @@ Download the chart archive for SlackerNews version 1.0.1, then add the archive t • Channel 32q8tKLfRFbHYPGJ1Q2E2vcDQ9j successfully set to release 1 ``` + :::tip + For automated workflows, you can create a `.replicated` configuration file to define your project structure and resources. This enables commands like `replicated release create --auto` to automatically discover and process resources without the `--yaml-dir` flag. See [.replicated Configuration File](/reference/cli-replicated-config). + ::: + ### Customize the Enterprise Portal Customize the look and feel of the Enterprise Portal for the SlackerNews application: diff --git a/sidebars.js b/sidebars.js index e0bc307250..9721cfa2b6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -608,6 +608,8 @@ const sidebars = { label: 'Replicated CLI', // This label is generated. Do not edit. items: [ // This list is generated. Do not edit. 'reference/replicated-cli-installing', + 'reference/cli-profiles', + 'reference/cli-replicated-config', 'reference/replicated', 'reference/replicated-cli-api', 'reference/replicated-cli-api-get', From 08c3f38d1c0154e7dd92bca7b31ba21a811a520e Mon Sep 17 00:00:00 2001 From: Noah Campbell Date: Wed, 22 Oct 2025 18:14:00 -0500 Subject: [PATCH 2/7] removed incorrect/outdated documentation --- docs/reference/replicated-cli-release-lint.mdx | 3 +-- docs/vendor/quick-start.mdx | 4 ---- docs/vendor/releases-creating-cli.mdx | 4 ---- 3 files changed, 1 insertion(+), 10 deletions(-) diff --git a/docs/reference/replicated-cli-release-lint.mdx b/docs/reference/replicated-cli-release-lint.mdx index 9e4bd242d5..6eb5de538e 100644 --- a/docs/reference/replicated-cli-release-lint.mdx +++ b/docs/reference/replicated-cli-release-lint.mdx @@ -4,7 +4,7 @@ Lint a directory of KOTS manifests ### Synopsis -Lint a directory of KOTS manifests. If a `.replicated` configuration file is present, the command will automatically discover and lint resources based on the configuration. Otherwise, use `--yaml-dir` to specify the directory containing manifest files. +Lint a directory of KOTS manifests. For more information about configuring automatic resource discovery, see [.replicated Configuration File](/reference/cli-replicated-config). @@ -19,7 +19,6 @@ replicated release lint [flags] -h, --help help for lint -o, --output string The output format to use. One of: json|table (default "table") --verbose Show verbose output, including discovered images - --yaml-dir yaml The directory containing multiple yamls for a Kots release. Cannot be used with the yaml flag. If omitted and a .replicated config exists, resources will be auto-discovered. ``` ### Options inherited from parent commands diff --git a/docs/vendor/quick-start.mdx b/docs/vendor/quick-start.mdx index 5c08347c5e..d79b10c3e8 100644 --- a/docs/vendor/quick-start.mdx +++ b/docs/vendor/quick-start.mdx @@ -550,10 +550,6 @@ Before you begin, do the following to set up your environment: :::note If you see a `helm-archive-missing` error, confirm that you have only one chart archive in `manifests` for version 1.0.1, and that the `chartVersion` in the HelmChart resource is also set to `1.0.1`. If you notice that any of the errors are from files in your `.history/` directory, run `rm -rf .history` and then lint the files again. ::: - - :::tip - For automated workflows, you can create a `.replicated` configuration file to define your project structure, resources, and linting preferences. This enables commands like `replicated release lint` to automatically discover and process resources without the `--yaml-dir` flag. See [.replicated Configuration File](/reference/cli-replicated-config). - ::: 1. Create and promote a new release, setting the version label of the release to `0.0.2`: diff --git a/docs/vendor/releases-creating-cli.mdx b/docs/vendor/releases-creating-cli.mdx index f6c53299c2..8a02d477bf 100644 --- a/docs/vendor/releases-creating-cli.mdx +++ b/docs/vendor/releases-creating-cli.mdx @@ -61,10 +61,6 @@ To create and promote a release: Where `PATH_TO_RELEASE_DIR` is the path to the directory with the release files. - :::note - If you have a `.replicated` configuration file, you can run `replicated release lint` without the `--yaml-dir` flag to automatically discover and lint resources. See [.replicated Configuration File](/reference/cli-replicated-config). - ::: - For more information, see [release lint](/reference/replicated-cli-release-lint) and [Linter Rules](/reference/linter). 1. Do one of the following: From 041cad9ee51012ca7b95c6a0509bf5fcc69bbf5e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 29 Oct 2025 13:15:56 -0600 Subject: [PATCH 3/7] docs edits --- .../_authorize-with-token-note.mdx | 2 +- .../replicated-cli/_install-docker.mdx | 27 +- docs/reference/cli-profiles.md | 179 ------------ ...> replicated-cli-config-file-reference.md} | 259 +++++------------- docs/reference/replicated-cli-config-file.md | 63 +++++ docs/reference/replicated-cli-installing.mdx | 116 +++++--- docs/vendor/environment-setup.mdx | 14 +- docs/vendor/quick-start.mdx | 4 - docs/vendor/releases-creating-cli.mdx | 14 +- docs/vendor/tutorial-helm-cli.mdx | 4 - sidebars.js | 10 +- 11 files changed, 223 insertions(+), 469 deletions(-) delete mode 100644 docs/reference/cli-profiles.md rename docs/reference/{cli-replicated-config.md => replicated-cli-config-file-reference.md} (57%) create mode 100644 docs/reference/replicated-cli-config-file.md diff --git a/docs/partials/replicated-cli/_authorize-with-token-note.mdx b/docs/partials/replicated-cli/_authorize-with-token-note.mdx index ca593013ba..7509b01790 100644 --- a/docs/partials/replicated-cli/_authorize-with-token-note.mdx +++ b/docs/partials/replicated-cli/_authorize-with-token-note.mdx @@ -1,3 +1,3 @@ :::note -The `replicated login` command creates a token after you log in to your vendor account in a browser and saves it to a config file. Alteratively, if you do not have access to a browser, you can set the `REPLICATED_API_TOKEN` environment variable to authenticate. For more information, see [(Optional) Set Environment Variables](/reference/replicated-cli-installing#env-var). +The `replicated login` command creates a token after you log in to your vendor account in a browser and saves it to a config file. ::: \ No newline at end of file diff --git a/docs/partials/replicated-cli/_install-docker.mdx b/docs/partials/replicated-cli/_install-docker.mdx index 5244b0b10e..64855ca3b1 100644 --- a/docs/partials/replicated-cli/_install-docker.mdx +++ b/docs/partials/replicated-cli/_install-docker.mdx @@ -2,8 +2,6 @@ For Windows users, Replicated recommends using Windows Subsystem for Linux (WSL2) and installing the Replicated using the Linux installations above. See [Linux / Windows Subsystem for Linux (WSL2)](#linux-wsl2). ::: -Installing in Docker environments requires that you set the `REPLICATED_API_TOKEN` environment variable to authorize the Replicated CLI with an API token. For more information, see [(Optional) Set Environment Variables](/reference/replicated-cli-installing#env-var). - To install and run the latest Replicated CLI in Docker environments: 1. Generate a service account or user API token in the vendor portal. To create new releases, the token must have `Read/Write` access. See [Generating API Tokens](/vendor/replicated-api-tokens). @@ -12,25 +10,8 @@ To install and run the latest Replicated CLI in Docker environments: Download and install the files. For simplicity, the usage in the next step is represented assuming that the CLI is downloaded and installed to the desktop. -1. Authorize the Replicated CLI: - - - Through a Docker container: - - ```shell - docker run \ - -e REPLICATED_API_TOKEN=$TOKEN \ - replicated/vendor-cli --help - ``` - Replace `TOKEN` with your API token. - - - On Windows: - - ```dos - docker.exe run \ - -e REPLICATED_API_TOKEN=%TOKEN% \ - replicated/vendor-cli --help - ``` - - Replace `TOKEN` with your API token. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth). - For more information about the `docker run` command, see [docker run](https://docs.docker.com/engine/reference/commandline/run/) in the Docker documentation. \ No newline at end of file + :::note + Installing in Docker environments requires that you set the `REPLICATED_API_TOKEN` environment variable to authorize the Replicated CLI with an API token. For more information, see [Set Environment Variables](/reference/replicated-cli-installing#env-var). + ::: \ No newline at end of file diff --git a/docs/reference/cli-profiles.md b/docs/reference/cli-profiles.md deleted file mode 100644 index dfeab189ab..0000000000 --- a/docs/reference/cli-profiles.md +++ /dev/null @@ -1,179 +0,0 @@ -# CLI Authentication Profiles - -The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials easily. This is useful when working with multiple Replicated accounts or environments. - -## Overview - -Authentication profiles store your API token and optionally custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). - -### Authentication Priority - -The CLI determines which credentials to use in the following order: - -1. `REPLICATED_API_TOKEN` environment variable (highest priority) -2. `--profile` flag (per-command override) -3. Default profile from `~/.replicated/config.yaml` -4. Legacy single token (backward compatibility) - -## Commands - -### `replicated profile add [profile-name]` - -Add a new authentication profile with the specified name. - -**Flags:** -- `--token` - API token for this profile (optional, will prompt if not provided). Supports environment variable expansion using `$VAR` or `${VAR}` syntax. - -**Examples:** - -```bash -# Add a production profile (will prompt for token) -replicated profile add prod - -# Add a production profile with token flag -replicated profile add prod --token=your-prod-token - -# Add a profile using an existing environment variable -replicated profile add prod --token='$REPLICATED_API_TOKEN' -``` - -If a profile with the same name already exists, it will be updated. If you add the first profile or if no default profile is set, the newly added profile will automatically become the default. - -**Note:** When using environment variables, make sure to quote the value (e.g., `'$REPLICATED_API_TOKEN'`) to prevent shell expansion and allow the CLI to expand it instead. - -### `replicated profile ls` - -List all authentication profiles. - -**Examples:** - -```bash -replicated profile ls -``` - -**Output:** - -``` - DEFAULT NAME API ORIGIN REGISTRY ORIGIN - * prod - dev -``` - -The asterisk (*) in the DEFAULT column indicates which profile is currently set as default. - -### `replicated profile use [profile-name]` - -Set the default authentication profile. - -**Examples:** - -```bash -replicated profile use prod -``` - -This command sets the specified profile as the default for all CLI operations. You can override the default on a per-command basis using the `--profile` flag. - -### `replicated profile edit [profile-name]` - -Edit an existing authentication profile. Only the flags you provide will be updated; other fields will remain unchanged. - -**Flags:** -- `--token` - New API token for this profile (optional). Supports environment variable expansion using `$VAR` or `${VAR}` syntax. - -**Examples:** - -```bash -# Update the token for a profile -replicated profile edit dev --token=new-dev-token - -# Update a profile using an environment variable -replicated profile edit dev --token='$REPLICATED_API_TOKEN' -``` - -### `replicated profile rm [profile-name]` - -Remove an authentication profile. - -**Examples:** - -```bash -replicated profile rm dev -``` - -If you remove the default profile and other profiles exist, one of the remaining profiles will be automatically set as the default. - -### `replicated profile set-default [profile-name]` - -Set the default authentication profile. This is an alias for `replicated profile use`. - -**Examples:** - -```bash -replicated profile set-default prod -``` - -## Usage Examples - -### Basic Workflow - -```bash -# Add a production profile using an existing environment variable -replicated profile add prod --token='$REPLICATED_API_TOKEN' - -# Add a development profile with a direct token -replicated profile add dev --token=your-dev-token - -# List all profiles -replicated profile ls - -# Switch to production profile -replicated profile use prod - -# Use development profile for a single command -replicated app ls --profile=dev - -# Edit a profile's token -replicated profile edit dev --token=new-dev-token - -# Remove a profile -replicated profile rm dev -``` - -### Working with Multiple Accounts - -```bash -# Add profiles for different accounts -replicated profile add company-a --token=token-a -replicated profile add company-b --token=token-b - -# Switch between accounts -replicated profile use company-a -replicated app ls # Lists apps for company-a - -replicated profile use company-b -replicated app ls # Lists apps for company-b -``` - -## Security - -- All credentials are stored in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only) -- Tokens are masked when prompted interactively -- Environment variables take precedence, allowing temporary overrides without modifying stored profiles - -## Troubleshooting - -### Profile Not Found - -If you see "profile not found", use `replicated profile ls` to list available profiles and verify the profile name. - -### Permission Denied - -If you encounter permission issues with `~/.replicated/config.yaml`, verify the file has the correct permissions: - -```bash -chmod 600 ~/.replicated/config.yaml -``` - -### Multiple Profiles, Wrong One Being Used - -Check the default profile with `replicated profile ls` and ensure the correct profile is marked with an asterisk (*). You can change the default with `replicated profile use [profile-name]`. diff --git a/docs/reference/cli-replicated-config.md b/docs/reference/replicated-cli-config-file-reference.md similarity index 57% rename from docs/reference/cli-replicated-config.md rename to docs/reference/replicated-cli-config-file-reference.md index 67aaccf492..a2abc8fefe 100644 --- a/docs/reference/cli-replicated-config.md +++ b/docs/reference/replicated-cli-config-file-reference.md @@ -1,91 +1,13 @@ -# .replicated Configuration File +# .replicated File Reference -The `.replicated` configuration file is used to define your project structure, resource locations, and linting preferences for the Replicated CLI. This file enables commands like `replicated release create` and `replicated release lint` to automatically discover and process your application resources. +This topic describes all supported fields in the `.replicated` configuration file. It also provides examples of `.replicated` configuration files. -## File Location +## Application Fields -The CLI searches for `.replicated` or `.replicated.yaml` starting from the current directory and walking up the directory tree. This supports both: -- Single-repository projects with one `.replicated` file at the root -- Monorepo projects with multiple `.replicated` files at different levels (configs are merged) - -## Creating a Configuration File - -### Using `replicated config init` - -The easiest way to create a `.replicated` file is using the interactive `init` command: - -```bash -# Interactive mode with prompts -replicated config init - -# Skip auto-detection -replicated config init --skip-detection -``` - -The `init` command will: -1. Auto-detect Helm charts, preflight specs, and support bundles in your project -2. Prompt for application configuration (app ID/slug) -3. Guide you through linting setup -4. Generate a `.replicated` file with your selections - -### Manual Creation - -You can also create a `.replicated` file manually using YAML format. - -## Configuration Structure - -Here's a complete example with all available fields: - -```yaml -# Application identification -appId: "" # Your application ID (optional) -appSlug: "" # Your application slug (optional, more commonly used) - -# Automatic promotion channels -promoteToChannelIds: [] # List of channel IDs to promote to -promoteToChannelNames: [] # List of channel names to promote to (e.g., ["beta", "stable"]) - -# Helm charts -charts: - - path: "./helm-chart" # Path or glob pattern to chart directory - chartVersion: "" # Override chart version (optional) - appVersion: "" # Override app version (optional) - -# Preflight checks -preflights: - - path: "./preflights/**" # Path or glob pattern to preflight specs - valuesPath: "./helm-chart" # Path to helm chart for template rendering (required for v1beta3 preflights) - -# Kubernetes manifests and support bundles -manifests: ["./support-bundles/**"] # Glob patterns for manifest files - -# Release labeling -releaseLabel: "" # Label pattern for releases (e.g., "v{{.Semver}}") - -# Linting configuration -repl-lint: - version: 1 - linters: - helm: - disabled: false # Enable/disable Helm linting - preflight: - disabled: false # Enable/disable preflight linting - support-bundle: - disabled: false # Enable/disable support bundle linting - tools: - helm: "latest" # Helm version (semantic version or "latest") - preflight: "latest" # Preflight version (semantic version or "latest") - support-bundle: "latest" # Support bundle version (semantic version or "latest") -``` - -## Field Reference - -### Application Fields - -#### `appId` (string, optional) +### `appId` (string, optional) Your Replicated application ID. You can find this in the Vendor Portal at vendor.replicated.com. -#### `appSlug` (string, optional) +### `appSlug` (string, optional) Your Replicated application slug. This is the human-readable identifier for your app (more commonly used than `appId`). **Example:** @@ -93,12 +15,12 @@ Your Replicated application slug. This is the human-readable identifier for your appSlug: "my-application" ``` -### Release Configuration +## Release Configuration -#### `promoteToChannelIds` (array of strings, optional) +### `promoteToChannelIds` (array of strings, optional) List of channel IDs to automatically promote releases to when using `replicated release create`. -#### `promoteToChannelNames` (array of strings, optional) +### `promoteToChannelNames` (array of strings, optional) List of channel names to automatically promote releases to. More convenient than using IDs. **Example:** @@ -106,7 +28,7 @@ List of channel names to automatically promote releases to. More convenient than promoteToChannelNames: ["beta", "stable"] ``` -#### `releaseLabel` (string, optional) +### `releaseLabel` (string, optional) Template string for release labels. Supports Go template syntax. **Example:** @@ -114,13 +36,13 @@ Template string for release labels. Supports Go template syntax. releaseLabel: "v{{.Semver}}" ``` -### Resource Configuration +## Resource Configuration -#### `charts` (array of objects, optional) +### `charts` (array of objects, optional) Helm charts to include in releases and lint operations. **Fields:** -- `path` (string, required): Path or glob pattern to chart directory (e.g., `./chart` or `./charts/*`) +- `path` (string, required): Path or glob pattern to chart directory (e.g., `./chart` or `./charts/*`). For more information, see [About Path Resolution](#about-path-resolution). - `chartVersion` (string, optional): Override the chart version - `appVersion` (string, optional): Override the app version @@ -132,11 +54,11 @@ charts: chartVersion: "1.2.3" ``` -#### `preflights` (array of objects, optional) +### `preflights` (array of objects, optional) Preflight check specifications to validate before installation. **Fields:** -- `path` (string, required): Path or glob pattern to preflight spec files +- `path` (string, required): Path or glob pattern to preflight spec files. For more information, see [About Path Resolution](#about-path-resolution). - `valuesPath` (string, optional but recommended): Path to Helm chart directory for template rendering. Required for v1beta3 preflights that use templating. **Example:** @@ -148,7 +70,7 @@ preflights: valuesPath: "./helm-chart" ``` -#### `manifests` (array of strings, optional) +### `manifests` (array of strings, optional) Glob patterns for Kubernetes manifest files, including support bundle specs. These are searched for support bundle specifications during linting. **Example:** @@ -158,9 +80,9 @@ manifests: - "./support-bundles/**" ``` -### Linting Configuration +## Linting Configuration -#### `repl-lint` (object, optional) +### `repl-lint` (object, optional) Configuration for the linting subsystem. **Fields:** @@ -189,7 +111,7 @@ repl-lint: support-bundle: "0.123.9" ``` -### Linter Configuration +## Linter Configuration Each linter under `repl-lint.linters` supports: - `disabled` (boolean): Set to `true` to disable the linter, `false` or omit to enable @@ -201,7 +123,7 @@ Each linter under `repl-lint.linters` supports: - `embedded-cluster`: Validates embedded cluster configurations (disabled by default) - `kots`: Validates KOTS manifests (disabled by default) -### Tool Versions +## Tool Versions The `tools` map specifies which versions of linting tools to use: @@ -221,10 +143,10 @@ tools: support-bundle: "latest" ``` -## Path Resolution +## About Path Resolution ### Relative Paths -All paths in the configuration file are resolved relative to the directory containing the `.replicated` file. This ensures commands work correctly regardless of where they're invoked. +All paths in the configuration file are resolved relative to the directory containing the `.replicated` file. This ensures commands work correctly regardless of where they are invoked. ### Glob Patterns Paths support glob patterns for flexible resource discovery: @@ -247,47 +169,53 @@ manifests: - "./*/manifests/**" # Manifests in any top-level directory ``` -## Monorepo Support +## Examples -For monorepo projects, you can have multiple `.replicated` files at different directory levels. The CLI will: -1. Find all `.replicated` files from the current directory up to the root -2. Merge them with child configurations taking precedence -3. Accumulate resources (charts, preflights, manifests) from all levels -4. Override scalar fields (appId, appSlug) with child values +### All Fields -**Example structure:** -``` -monorepo/ -├── .replicated # Root config with shared settings -│ └── appSlug: "company-suite" -├── service-a/ -│ ├── .replicated # Service A specific config -│ │ └── charts: ["./chart"] -│ └── chart/ -└── service-b/ - ├── .replicated # Service B specific config - │ └── charts: ["./helm"] - └── helm/ -``` +```yaml +# Application identification +appId: "" # Your application ID (optional) +appSlug: "" # Your application slug (optional, more commonly used) -When running from `monorepo/service-a/`, both configs are merged: -- `appSlug` from root is used (unless overridden in child) -- Charts from both configs are included -- Lint settings are merged with child taking precedence +# Automatic promotion channels +promoteToChannelIds: [] # List of channel IDs to promote to +promoteToChannelNames: [] # List of channel names to promote to (e.g., ["beta", "stable"]) -## Auto-Discovery Mode +# Helm charts +charts: + - path: "./helm-chart" # Path or glob pattern to chart directory + chartVersion: "" # Override chart version (optional) + appVersion: "" # Override app version (optional) -If no `.replicated` file is found, the CLI operates in auto-discovery mode: -- Automatically searches for Helm charts in the current directory -- Auto-detects preflight specs (files with `kind: Preflight`) -- Auto-detects support bundle specs (files with `kind: SupportBundle`) -- Uses default linting configuration +# Preflight checks +preflights: + - path: "./preflights/**" # Path or glob pattern to preflight specs + valuesPath: "./helm-chart" # Path to helm chart for template rendering (required for v1beta3 preflights) -This allows quick testing without configuration, but creating a `.replicated` file is recommended for consistent builds. +# Kubernetes manifests and support bundles +manifests: ["./support-bundles/**"] # Glob patterns for manifest files -## Examples +# Release labeling +releaseLabel: "" # Label pattern for releases (e.g., "v{{.Semver}}") + +# Linting configuration +repl-lint: + version: 1 + linters: + helm: + disabled: false # Enable/disable Helm linting + preflight: + disabled: false # Enable/disable preflight linting + support-bundle: + disabled: false # Enable/disable support bundle linting + tools: + helm: "latest" # Helm version (semantic version or "latest") + preflight: "latest" # Preflight version (semantic version or "latest") + support-bundle: "latest" # Support bundle version (semantic version or "latest") +``` -### Simple Single-Chart Project +### Single-Chart ```yaml appSlug: "my-application" @@ -376,69 +304,4 @@ preflights: ```yaml # Minimal config - relies on auto-detection appSlug: "simple-app" -``` - -## Usage with CLI Commands - -### Linting -```bash -# Lint all resources defined in .replicated -replicated release lint - -# With verbose output (shows discovered images) -replicated release lint --verbose - -# JSON output -replicated release lint --output json -``` - -### Creating Releases -```bash -# Create release with resources from .replicated -replicated release create --auto - -# Create and automatically promote to channels from config -replicated release create --auto --promote -``` - -### Initialization -```bash -# Interactive setup -replicated config init -``` - -## Best Practices - -1. **Version Control**: Always commit `.replicated` to version control -2. **Use Glob Patterns**: Leverage globs for flexible resource discovery -3. **Pin Tool Versions**: Use specific versions in CI/CD for reproducible builds -4. **Document Custom Paths**: Add comments for non-standard path structures -5. **Start Simple**: Begin with minimal config and expand as needed -6. **Test Locally**: Run `replicated release lint` before committing -7. **Monorepo Organization**: Use parent configs for shared settings, child configs for service-specific resources - -## Troubleshooting - -### Config Not Found -If the CLI can't find your `.replicated` file: -- Ensure it's named `.replicated` or `.replicated.yaml` -- Check that it's in the current directory or a parent directory -- Verify file permissions (should be readable) - -### Invalid Glob Patterns -If you see glob pattern errors: -- Ensure patterns use valid glob syntax -- Test patterns with `ls` or `find` commands first -- Quote patterns in shell commands to prevent shell expansion - -### Tool Version Errors -If tool version resolution fails: -- Use `"latest"` for automatic version detection -- Specify semantic versions without `v` prefix (e.g., `"3.14.4"`) -- Check internet connectivity for latest version fetching - -### Merge Conflicts in Monorepos -If resource merging isn't working as expected: -- Check file paths are relative to each config file -- Verify both configs are valid YAML -- Use `--debug` flag to see merge details +``` \ No newline at end of file diff --git a/docs/reference/replicated-cli-config-file.md b/docs/reference/replicated-cli-config-file.md new file mode 100644 index 0000000000..22fa1d10b3 --- /dev/null +++ b/docs/reference/replicated-cli-config-file.md @@ -0,0 +1,63 @@ +# Add a .replicated File + +This topic describes the `.replicated` configuration file, including how to add a `.replicated` file and how the Replicated CLI uses this file to discover and process your application resources when linting and creating releases. + +For a reference that describes the fields in the `.replicated` file, see [.replicated File Reference](/reference/replicated-cli-replicated-config-reference). + +## Overview + +You can add a `.replicated` configuration file to set various preferences for the Replicated CLI, such as the application slug, the channel ID for promoting releases, paths to your application resources (including Helm charts, preflight specs, or Kubernetes manifests), and more. This file enables commands like [`replicated release create`](/reference/replicated-cli-release-create) and [`replicated release lint`](/reference/replicated-cli-release-lint) to automatically discover your application resources and preferences to help ensure consistent builds when managing releases from the Replicated CLI. + +The Replicated CLI searches for `.replicated` or `.replicated.yaml` files starting from the current directory and walking up the directory tree. If no `.replicated` file is found, the Replicated CLI: +- Automatically searches for Helm charts in the current directory +- Auto-detects preflight specs (files with `kind: Preflight`) +- Auto-detects support bundle specs (files with `kind: SupportBundle`) +- Uses default linting configuration + +## About Using Multiple `.replicated` Files for Monorepos + +The Replicated CLI supports both single-repository projects with one `.replicated` file at the root and monorepo projects with multiple `.replicated` files at different levels. + +For monorepo projects with multiple `.replicated` files, the Replicated CLI: +- Finds all `.replicated` files from the current directory up to the root +- Merges the configuration files, with the settings from child configuration files taking precedence +- Accumulates resources (charts, preflights, manifests) from all levels +- Overrides scalar fields (appId, appSlug) with values from child configuration files + +The following provides an example of a monorepo structure with multiple `.replicated` configuration files: + +``` +monorepo/ +├── .replicated # Root config with shared settings +│ └── appSlug: "company-suite" +├── service-a/ +│ ├── .replicated # Service A specific config +│ │ └── charts: ["./chart"] +│ └── chart/ +└── service-b/ + ├── .replicated # Service B specific config + │ └── charts: ["./helm"] + └── helm/ +``` + +In the example above, when running `replicated release lint` or `replicated release create` from `monorepo/service-a/` or from `monorepo/service-b/`, the Replicated CLI merges the root `.replicated` file with the relevant child `.replicated` file: +- The `appSlug` from the root `.replicated` file is used, unless the slug is overridden in the child configuration file +- Charts from both `.replicated` files are included +- Lint settings are merged, with the settings from the child `.replicated` file taking precedence + +## Add a `.replicated` File + +This section explains how to generate a `.replicated` file using the `replicated config init` command. Alternatively, you can manually create a `.replicated` file. For a field reference and examples, see [.replicated File Reference](/reference/replicated-cli-replicated-config-reference). + +To generate a `.replicated` configuration file using the Replicated CLI: + +1. Run: + + ```bash + replicated config init + ``` + The `replicated config init` command automatically detects Helm charts, preflight specs, and support bundles in your project. + +1. Respond to the prompts in the output of this command to set your application configuration and linting preferences. + + The `.replicated` file is generated based on your selections. \ No newline at end of file diff --git a/docs/reference/replicated-cli-installing.mdx b/docs/reference/replicated-cli-installing.mdx index a645f08d13..1340cf73f4 100644 --- a/docs/reference/replicated-cli-installing.mdx +++ b/docs/reference/replicated-cli-installing.mdx @@ -20,14 +20,9 @@ Complete the following prerequisites before installing the Replicated CLI: - Create a vendor account. See [Create a Vendor Account](/vendor/vendor-portal-creating-account). - To run on Linux or Mac, install [curl](https://curl.haxx.se/). - To run through a Docker container, install [docker](https://www.docker.com). +- (Recommended) For Windows users, install Linux on Windows using WSL2. See [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install). -## Install and Run - -You can install and run the Replicated CLI in the following environments: - -* Directly on MacOS -* Directly on Linux -* Through Docker (Useful for Windows, GitHub Actions, or computers without sufficient access) +## Install ### MacOS @@ -39,11 +34,7 @@ To install and run the latest Replicated CLI on MacOS: 1. -1. - - - -1. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth). ### Linux / Windows Subsystem for Linux (WSL) {#linux-wsl2} @@ -57,37 +48,77 @@ To install and run the latest Replicated CLI on Linux or Windows Subsystem for L 1. -1. - - - -1. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth). ### Docker / Windows -## (Optional) Set Environment Variables {#env-var} +## Authenticate {#auth} + +After installing the Replicated CLI, authenticate with your Replicated credentials using one of the following methods: +* Set the `REPLICATED_API_TOKEN` environment variable to your API token +* Create a Replicated profile at `~/.replicated/config.yaml` to store your API token +* Generate a single authentication token by running `replicated login` + +The Replicated CLI determines which credentials to use for authentication in the following order: + +1. `REPLICATED_API_TOKEN` environment variable. Environment variables take precedence, allowing temporary overrides without modifying stored profiles. +2. Replicated profile passed with the `--profile` flag. This allows for a per-command override of the default Replicated profile. +3. Default Replicated profile from `~/.replicated/config.yaml` +4. Single token auth with `replicated login` + +### Add Replicated Profiles {#profiles} + +The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials. This is useful when working with multiple Replicated accounts or environments. -The Replicated CLI supports setting the following environment variables: +Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). Tokens are masked when prompted interactively from the CLI. -* **`REPLICATED_API_TOKEN`**: A service account or user API token generated from a vendor portal team or individual account. The `REPLICATED_API_TOKEN` environment variable has the following use cases: +The following examples show how to add and work with Replicated profiles: - * To use Replicated CLI commands as part of automation (such as from continuous integration and continuous delivery pipelines), authenticate by providing the `REPLICATED_API_TOKEN` environment variable. +```bash +# Add a production profile using an existing environment variable +replicated profile add prod --token='$REPLICATED_API_TOKEN' - * To authorize the Replicated CLI when installing and running the CLI in Docker containers. +# Add a development profile with a direct token +replicated profile add dev --token=your-dev-token - * Optionally set the `REPLICATED_API_TOKEN` environment variable instead of using the `replicated login` command to authorize the Replicated CLI in MacOS or Linux environments. +# List all profiles +replicated profile ls - :::note - The `REPLICATED_API_TOKEN` environment variable takes precedence over authentication profiles. For more information about authentication profiles, see [CLI Authentication Profiles](/reference/cli-profiles). - ::: +# Switch to production profile +replicated profile use prod -* **`REPLICATED_APP`**: The slug of the target application. +# Use development profile for a single command +replicated app ls --profile=dev - When using the Replicated CLI to manage applications through your vendor account (including channels, releases, customers, or other objects associated with an application), you can set the `REPLICATED_APP` environment variable to avoid passing the application slug with each command. +# Edit a profile's token +replicated profile edit dev --token=new-dev-token -### `REPLICATED_API_TOKEN` +# Remove a profile +replicated profile rm dev + +# Add profiles for different accounts +replicated profile add company-a --token=token-a +replicated profile add company-b --token=token-b + +# Switch between accounts +replicated profile use company-a +replicated app ls # Lists apps for company-a + +replicated profile use company-b +replicated app ls # Lists apps for company-b +``` + +{/* UPDATE LINK For more information, see [replicated profile](/replicated-cli-profile). */} + +### Set Environment Variables {#env-var} + +#### Set REPLICATED_API_TOKEN + +The `REPLICATED_API_TOKEN` environment variable can be set to a service account or user API token generated from a Vendor Portal team or individual account. + +The `REPLICATED_API_TOKEN` environment variable is required to authorize the Replicated CLI when installing and running the CLI in Docker containers. It is also helpful for running Replicated CLI commands as part of automation in CI/CD pipelines. To set the `REPLICATED_API_TOKEN` environment variable: @@ -117,13 +148,21 @@ To set the `REPLICATED_API_TOKEN` environment variable: replicated/vendor-cli --help ``` -### `REPLICATED_APP` +#### Set REPLICATED_APP + +When using the Replicated CLI to manage applications through your vendor account, you can set the `REPLICATED_APP` environment variable to the target application slug to avoid having to pass the slug with each command. To set the `REPLICATED_APP` environment variable: -1. In the [vendor portal](https://vendor.replicated.com), go to the **Application Settings** page and copy the slug for the target application. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Application_. +1. Get the application slug: + + ``` + replicated app ls + ``` + + Or, in the [Vendor Portal](https://vendor.replicated.com), go to the **Application Settings** page and copy the slug for the target application. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Application_. -1. Set the environment variable, replacing `APP_SLUG` with the slug for the target application that you retreived in the previous step: +1. Set the environment variable, replacing `APP_SLUG` with the slug that you copied in the previous step: * **MacOs or Linux**: @@ -138,6 +177,7 @@ To set the `REPLICATED_APP` environment variable: -e REPLICATED_APP=$APP_SLUG replicated/vendor-cli --help ``` + For more information about the `docker run` command, see [docker run](https://docs.docker.com/engine/reference/commandline/run/) in the Docker documentation. * **Windows**: @@ -147,8 +187,14 @@ To set the `REPLICATED_APP` environment variable: replicated/vendor-cli --help ``` -## Manage Authentication with Profiles +### `replicated login` {#login} + +The `replicated login` command creates a token after you log in to your vendor account in a browser and saves it to a config file. -The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials easily. This is useful when working with multiple Replicated accounts or environments. +Using the `replicated login` command requires browser access. If you do not have access to a browser, you can authenticate by adding a Replicated profile or setting the `REPLICATED_API_TOKEN` environment variable instead. See [Add Replicated Profiles](#profiles) or [Set Environment Variables](#env-var). + +To authenticate using `replicated login`: + +1. -For complete information about authentication profiles, including how to create, manage, and switch between profiles, see [CLI Authentication Profiles](/reference/cli-profiles). +1. \ No newline at end of file diff --git a/docs/vendor/environment-setup.mdx b/docs/vendor/environment-setup.mdx index 27eeadd6cf..c6aa523173 100644 --- a/docs/vendor/environment-setup.mdx +++ b/docs/vendor/environment-setup.mdx @@ -97,7 +97,7 @@ sudo mv linux-amd64/helm /usr/local/bin/helm The Replicated CLI is the primary interface for the Replicated Platform. With the Replicated CLI, you can create and manage applications, releases, channels, customers, and more. You also use the Replicated CLI to create clusters with the Compatibility Matrix. -After installing, you can authorize the Replicated CLI by logging in to your Replicated vendor account through the `replicated login` command. +After installing, authorize the Replicated CLI using the Replicated credentials to begin working with your applications. See [Authenticate](#auth) in _Install the Replicated CLI_. For more information about installing and authorizing the Replicated CLI, see [Install the Replicated CLI](/reference/replicated-cli-installing). @@ -111,11 +111,7 @@ To install and run the latest Replicated CLI on MacOS: 1. -1. - - - -1. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_. #### Linux / Windows Subsystem for Linux (WSL2) {#linux-wsl2} @@ -129,11 +125,7 @@ To install and run the latest Replicated CLI on Linux or Windows Subsystem for L 1. -1. - - - -1. +1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_. #### Docker / Windows diff --git a/docs/vendor/quick-start.mdx b/docs/vendor/quick-start.mdx index d79b10c3e8..96670ab93f 100644 --- a/docs/vendor/quick-start.mdx +++ b/docs/vendor/quick-start.mdx @@ -90,10 +90,6 @@ Before you begin, do the following to set up your environment: ``` In the browser window that opens, follow the prompt to log in to your Vendor Portal account and authorize the CLI. - :::tip - The CLI also supports multiple authentication profiles for managing different accounts. See [CLI Authentication Profiles](/reference/cli-profiles). - ::: - 1. Create an application named `SlackerNews`: ```bash diff --git a/docs/vendor/releases-creating-cli.mdx b/docs/vendor/releases-creating-cli.mdx index 8a02d477bf..9e6a25379a 100644 --- a/docs/vendor/releases-creating-cli.mdx +++ b/docs/vendor/releases-creating-cli.mdx @@ -6,25 +6,15 @@ For information about creating and managing releases with the Vendor Portal, see For information about creating and managing releases with the Vendor API v3, see the [releases](https://replicated-vendor-api.readme.io/reference/createrelease) section in the Vendor API v3 documentation. -:::tip -You can use a `.replicated` configuration file to define your project structure and resource locations. See [.replicated Configuration File](/reference/cli-replicated-config). -::: - ## Prerequisites Before you create a release using the Replicated CLI, complete the following prerequisites: -* Install the Replicated CLI and then log in to authorize the CLI. See [Install the Replicated CLI](/reference/replicated-cli-installing). +* Install the Replicated CLI. See [Install the Replicated CLI](/reference/replicated-cli-installing). * Create a new application using the `replicated app create APP_NAME` command. You only need to do this procedure one time for each application that you want to deploy. See [`app create`](/reference/replicated-cli-app-create) in _Reference_. -* Set the `REPLICATED_APP` environment variable to the slug of the target application. See [Set Environment Variables](/reference/replicated-cli-installing#env-var) in _Installing the Replicated CLI_. - - **Example**: - - ```bash - export REPLICATED_APP=my-app-slug - ``` +* Add a `.replicated` configuration file to your project. See [Add a .replicated File](/reference/replicated-cli-config-file). Alternatively, set the `REPLICATED_APP` environment variable to the slug of the target application. See [Set Environment Variables](/reference/replicated-cli-installing#env-var) in _Installing the Replicated CLI_. ## Create a Release From a Local Directory {#dir} diff --git a/docs/vendor/tutorial-helm-cli.mdx b/docs/vendor/tutorial-helm-cli.mdx index d7087de0d1..dce730ec09 100644 --- a/docs/vendor/tutorial-helm-cli.mdx +++ b/docs/vendor/tutorial-helm-cli.mdx @@ -113,10 +113,6 @@ Download the chart archive for SlackerNews version 1.0.1, then add the archive t • Channel 32q8tKLfRFbHYPGJ1Q2E2vcDQ9j successfully set to release 1 ``` - :::tip - For automated workflows, you can create a `.replicated` configuration file to define your project structure and resources. This enables commands like `replicated release create --auto` to automatically discover and process resources without the `--yaml-dir` flag. See [.replicated Configuration File](/reference/cli-replicated-config). - ::: - ### Customize the Enterprise Portal Customize the look and feel of the Enterprise Portal for the SlackerNews application: diff --git a/sidebars.js b/sidebars.js index 9721cfa2b6..9341a61f5e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -608,8 +608,6 @@ const sidebars = { label: 'Replicated CLI', // This label is generated. Do not edit. items: [ // This list is generated. Do not edit. 'reference/replicated-cli-installing', - 'reference/cli-profiles', - 'reference/cli-replicated-config', 'reference/replicated', 'reference/replicated-cli-api', 'reference/replicated-cli-api-get', @@ -719,6 +717,14 @@ const sidebars = { 'reference/replicated-cli-vm-versions', ], }, + { + type: 'category', + label: 'Replicated CLI Configuration File', + items: [ + 'reference/replicated-cli-config-file', + 'reference/replicated-cli-config-file-reference', + ], + }, { type: 'category', label: 'KOTS CLI', From 0a349660799559ad91f86f6689dcca98ef73119f Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 29 Oct 2025 13:52:38 -0600 Subject: [PATCH 4/7] docs edits --- docs/vendor/environment-setup.mdx | 2 +- docs/vendor/replicated-api-tokens.md | 26 ++++++++++---------------- 2 files changed, 11 insertions(+), 17 deletions(-) diff --git a/docs/vendor/environment-setup.mdx b/docs/vendor/environment-setup.mdx index c6aa523173..c0de6b750d 100644 --- a/docs/vendor/environment-setup.mdx +++ b/docs/vendor/environment-setup.mdx @@ -97,7 +97,7 @@ sudo mv linux-amd64/helm /usr/local/bin/helm The Replicated CLI is the primary interface for the Replicated Platform. With the Replicated CLI, you can create and manage applications, releases, channels, customers, and more. You also use the Replicated CLI to create clusters with the Compatibility Matrix. -After installing, authorize the Replicated CLI using the Replicated credentials to begin working with your applications. See [Authenticate](#auth) in _Install the Replicated CLI_. +After installing, authorize the Replicated CLI using your Replicated credentials. See [Authenticate](#auth) in _Install the Replicated CLI_. For more information about installing and authorizing the Replicated CLI, see [Install the Replicated CLI](/reference/replicated-cli-installing). diff --git a/docs/vendor/replicated-api-tokens.md b/docs/vendor/replicated-api-tokens.md index 2bd58faa7e..de610660b7 100644 --- a/docs/vendor/replicated-api-tokens.md +++ b/docs/vendor/replicated-api-tokens.md @@ -4,16 +4,14 @@ import TeamTokenNote from "../partials/vendor-api/_team-token-note.mdx" This topic describes the available types of API tokens and how to generate them for use with the Replicated CLI and Replicated Vendor API v3. +The Replicated CLI also supports creating multiple authentication profiles for managing tokens across different accounts or environments. For more information, see [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_. + ## About API Tokens The Vendor API v3 is the API that manages applications in the Replicated Vendor Portal. The Replicated CLI is an implementation of the Vendor API v3. Using the Replicated CLI and Vendor API V3 requires an API token for authorization. Tokens are primarily used for automated customer, channel, and release management. You create tokens in the Vendor Portal. -:::tip -The Replicated CLI supports multiple authentication profiles for managing tokens across different accounts or environments. See [CLI Authentication Profiles](/reference/cli-profiles). -::: - The following types of tokens are available: - [Service Accounts](#service-accounts) @@ -68,13 +66,11 @@ To generate a service account: 1. Copy the service account token and save it in a secure location. The token will not be available to view again. - :::tip - You can store this token in a CLI authentication profile for easy management. See [CLI Authentication Profiles](/reference/cli-profiles). - ::: +1. (Recommended) Add the token to a Replicated authentication profile. See [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_. - :::note - To remove a service account, select **Remove** for the service account that you want to delete. - ::: +:::note +To remove a service account, select **Remove** for the service account that you want to delete. +::: ### Generate a User API Token @@ -101,10 +97,8 @@ To generate a user API token: 1. Copy the user API token that displays and save it in a secure location. The token will not be available to view again. - :::tip - You can store this token in a CLI authentication profile for easy management. See [CLI Authentication Profiles](/reference/cli-profiles). - ::: +1. (Recommended) Add the token to a Replicated authentication profile. See [Authenticate](/reference/replicated-cli-installing#auth) in _Installing the Replicated CLI_. - :::note - To revoke a token, select **Revoke token** for the token that you want to delete. - ::: +:::note +To revoke a token, select **Revoke token** for the token that you want to delete. +::: \ No newline at end of file From 8a27aceaafcaab95bb357b2ec9e04227db2add5b Mon Sep 17 00:00:00 2001 From: Noah Campbell Date: Fri, 31 Oct 2025 09:36:18 -0500 Subject: [PATCH 5/7] Update docs/reference/replicated-cli-config-file.md Co-authored-by: Paige Calvert --- docs/reference/replicated-cli-config-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/replicated-cli-config-file.md b/docs/reference/replicated-cli-config-file.md index 22fa1d10b3..9dc205486b 100644 --- a/docs/reference/replicated-cli-config-file.md +++ b/docs/reference/replicated-cli-config-file.md @@ -6,7 +6,7 @@ For a reference that describes the fields in the `.replicated` file, see [.repli ## Overview -You can add a `.replicated` configuration file to set various preferences for the Replicated CLI, such as the application slug, the channel ID for promoting releases, paths to your application resources (including Helm charts, preflight specs, or Kubernetes manifests), and more. This file enables commands like [`replicated release create`](/reference/replicated-cli-release-create) and [`replicated release lint`](/reference/replicated-cli-release-lint) to automatically discover your application resources and preferences to help ensure consistent builds when managing releases from the Replicated CLI. +You can add a `.replicated` configuration file to set various preferences for the Replicated CLI, such as the application slug, the channel ID for promoting releases, paths to your application resources (including Helm charts, preflight specs, or Kubernetes manifests), and more. This file enables the [`replicated release create`](/reference/replicated-cli-release-create) and [`replicated release lint`](/reference/replicated-cli-release-lint) commands to automatically discover your application resources and preferences to help ensure consistent builds when managing releases from the Replicated CLI. The Replicated CLI searches for `.replicated` or `.replicated.yaml` files starting from the current directory and walking up the directory tree. If no `.replicated` file is found, the Replicated CLI: - Automatically searches for Helm charts in the current directory From 91c180587b54ad49acf12cd680d16beb664c4e68 Mon Sep 17 00:00:00 2001 From: Noah Campbell Date: Fri, 31 Oct 2025 10:10:55 -0500 Subject: [PATCH 6/7] Update docs/reference/replicated-cli-release-lint.mdx Co-authored-by: Paige Calvert --- docs/reference/replicated-cli-release-lint.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/replicated-cli-release-lint.mdx b/docs/reference/replicated-cli-release-lint.mdx index 6eb5de538e..c8380afd45 100644 --- a/docs/reference/replicated-cli-release-lint.mdx +++ b/docs/reference/replicated-cli-release-lint.mdx @@ -6,7 +6,7 @@ Lint a directory of KOTS manifests Lint a directory of KOTS manifests. -For more information about configuring automatic resource discovery, see [.replicated Configuration File](/reference/cli-replicated-config). +For information about setting linting preferences for your project, see [Add a .replicated File](/reference/replicated-cli-config-file). ``` replicated release lint [flags] From ef8bf4345adb0af33faabd81ee6a052d8ff8893d Mon Sep 17 00:00:00 2001 From: Noah Campbell Date: Fri, 31 Oct 2025 10:13:47 -0500 Subject: [PATCH 7/7] Update docs/reference/replicated-cli-installing.mdx Co-authored-by: Paige Calvert --- docs/reference/replicated-cli-installing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/replicated-cli-installing.mdx b/docs/reference/replicated-cli-installing.mdx index 1340cf73f4..1241eaa72c 100644 --- a/docs/reference/replicated-cli-installing.mdx +++ b/docs/reference/replicated-cli-installing.mdx @@ -72,7 +72,7 @@ The Replicated CLI determines which credentials to use for authentication in the The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials. This is useful when working with multiple Replicated accounts or environments. -Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). Tokens are masked when prompted interactively from the CLI. +Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). The following examples show how to add and work with Replicated profiles: