Replicated CLI project configuration

The .replicated file is a per-project configuration file that the Replicated CLI uses. Place this file at the root of your project repository. It tells the CLI which application, Helm charts, Kubernetes manifests, and preflight checks belong to this project.

When you run commands like replicated release create without explicit flags, the CLI searches for this file in the current directory. It continues searching upward through parent directories.

replicated release lint uses .replicated only when the release validation v2 feature flag is active or when the REPLICATED_RELEASE_VALIDATION_V2 environment variable is set to 1.

File location and name

Place the file at the root of your project. The CLI searches from the current working directory up through parent directories. It accepts either of these names:

• .replicated
• .replicated.yaml

What it configures

The .replicated file configures the following:

• Application identity: which Replicated app this project belongs to
• Charts: Helm charts to package as part of a release
• Manifests: raw Kubernetes YAML files to include in a release
• Preflights: preflight check specs to validate before install
• Linting: local lint tool configuration and version pinning

Field reference

appSlug (string, optional)

The slug of your Replicated application. Commands that need to know which app to operate on, such as replicated release create, use this field. You can also provide this with the --app flag or the REPLICATED_APP environment variable.

appSlug: "my-application"

appId (string, optional)

The UUID of your Replicated application. Alternative to appSlug. If both are present, the CLI prefers appSlug.

appId: "12345678-1234-1234-1234-123456789abc"

charts (list, optional)

Helm charts to package when creating a release. Each entry is a chart with the following fields:

Field	Type	Required	Description
path	string	Yes	Path to the chart directory. Can be a glob pattern. Resolved relative to the .replicated file.
chartVersion	string	No	Override the chart version.
appVersion	string	No	Override the application version.

charts:
  - path: ./chart
  - path: ./charts/backend
    chartVersion: "1.2.3"
    appVersion: "v2.0.0"

manifests (list of strings, optional)

Glob patterns that match Kubernetes manifest YAML files to include in the release. Resolve these patterns relative to the .replicated file.

manifests:
  - ./manifests/*.yaml
  - ./crds/**/*.yaml

preflights (list, optional)

Preflight check specifications to lint and validate. Each entry has the following fields:

Field	Type	Required	Description
path	string	Yes	Path to the preflight spec file.
chartName	string	No	Explicit chart name to associate with this preflight.
chartVersion	string	No	Explicit chart version. Provide this together with chartName.

preflights:
  - path: ./preflight.yaml
  - path: ./preflights/ha-checks.yaml
    chartName: my-app
    chartVersion: "1.0.0"

repl-lint (object, optional)

Configuration for the local linting engine. This controls which linters run and which tool versions to use.

Field	Type	Description
version	integer	Lint config schema version. Defaults to 1.
linters	object	Toggle individual linters on or off.
tools	map	Pin tool versions (e.g. helm: "3.14.4"). Defaults to "latest".

Linter configuration

Each linter in linters supports a disabled boolean:

repl-lint:
  version: 1
  linters:
    helm:
      disabled: false        # on by default
    preflight:
      disabled: false        # on by default
    support-bundle:
      disabled: false        # on by default
    embedded-cluster:
      disabled: true         # off by default (opt-in)

The kots linter is parsed by the config but is not currently implemented. Enabling it has no effect.

The embedded-cluster linter also supports:

Field	Type	Description
disable-checks	list of strings	Checker IDs to skip. Defaults to ["helmchart-archive", "ecconfig-helmchart-archive"].
binary-path	string	Path to a custom embedded-cluster binary.

Tool version pinning

You can pin the versions of external tools that the linters use:

repl-lint:
  tools:
    helm: "3.14.4"
    preflight: "latest"
    support-bundle: "latest"

Versions must be either a semantic version (1.2.3 or v1.2.3) or the string latest.

The embedded-cluster linter discovers its version from the manifests instead of the tools map. Setting it in .replicated has no effect.

App resolution precedence

When a command needs to know which app to target, it resolves the value in this order:

1. --app flag
2. REPLICATED_APP environment variable
3. .replicated file (appSlug or appId)
4. Cached default app from replicated default app <slug>

Monorepo support

If you have a monorepo with multiple apps, you can place a .replicated file in each app subdirectory. The CLI searches upward from the current working directory and merges all found configuration files:

• Scalar fields (appSlug, appId): child overrides parent.
• Resource arrays (charts, preflights, manifests): accumulate from all levels.
• repl-lint: child overrides parent settings.

This lets you define common settings at the repo root and app-specific settings in subdirectories.

Examples

Minimal Helm-only project

appSlug: "my-helm-app"
charts:
  - path: ./chart

KOTS manifests project

appSlug: "my-kots-app"
manifests:
  - ./manifests/*.yaml
  - ./crds/**/*.yaml

Multi-chart project with linting

appSlug: "my-platform"
charts:
  - path: ./charts/api
  - path: ./charts/worker
manifests:
  - ./manifests/*.yaml
  - ./configmaps/*.yaml
preflights:
  - path: ./preflights/cluster-checks.yaml
    chartName: api
    chartVersion: "1.0.0"
repl-lint:
  version: 1
  linters:
    helm:
      disabled: false
    preflight:
      disabled: false
    support-bundle:
      disabled: true

Monorepo root configuration

# At repo root: .replicated
repl-lint:
  version: 1
  linters:
    helm:
      disabled: false

# At apps/frontend/.replicated
appSlug: "frontend-app"
charts:
  - path: ./chart
manifests:
  - ./manifests/*.yaml

# At apps/backend/.replicated
appSlug: "backend-app"
charts:
  - path: ./chart
manifests:
  - ./manifests/*.yaml

Create a configuration file

Run the interactive initialization command to generate a .replicated file for your project:

replicated config init

For non-interactive environments (e.g., CI):

replicated config init --non-interactive