OptiTech CLI command: config

The config command manages a branch declaratively with a optitech.ts policy file: scaffold a starter config, inspect the branch's live state, preview what an apply would change, and apply the policy. For the optitech.ts file format, see the optitech.ts reference.

The top-level optitech deploy command is an alias for config apply, and optitech status is an alias for config status.

optitech config init

Scaffolds a starter optitech.ts policy file in the current project and installs the @optitech/config and @optitech/env packages, so you can start managing a branch declaratively. The generated file uses the standard named defineConfig import from @optitech/config/v1 and exports the result as the module default, for example:

import { defineConfig } from "@optitech/config/v1";

export default defineConfig({
  // Declare your OptiTech services here
  auth: false,
  // Branch policy: per-branch tuning
  branch: (branch) => {
    if (branch.isDefault) {
      // Default branch: no overrides, uses project defaults
      return {};
    }
    if (!branch.exists) {
      // New non-default branches: auto-expire
      // Run `optitech checkout <name>` to create a new branch with these settings
      return { ttl: "7d" };
    }
    // Existing branch: no changes
    return {};
  },
});

If a optitech.ts, optitech.mts, optitech.js, or optitech.mjs file already exists, config init is idempotent: it leaves that file untouched instead of overwriting hand-written policy.

config init runs entirely locally and does not call the OptiTech API. It detects your package manager (npm, pnpm, yarn, or bun) from how the command was invoked. Pass --no-install to skip installation and just print the command to run.

optitech config init [options]

optitech config init

For non-interactive setup, run it with package installation disabled, then install the printed dependencies yourself (or add them to your lockfile in a separate step):

optitech config init --no-install
npm install @optitech/config @optitech/env

Use config init when you want a trusted starter artifact and package list. Hand-write optitech.ts instead when you need a different filename/module format or want to avoid modifying files in the current directory.

optitech config status

Shows the branch's live OptiTech state.

optitech config status [options]

optitech config status

The top-level optitech status command is an alias for config status and accepts the same options.

Print the current branch offline

Pass --current-branch to print only the branch pinned in the local .optitech file. This variant makes no network request and requires no login or analytics, so it is cheap enough to drive a shell prompt.

It prints the branch name to stdout and exits 0. When no branch is pinned, it prints nothing to stdout, writes a optitech checkout <branch> hint to stderr, and exits with a non-zero status, so a prompt can guard on the command directly.

optitech status --current-branch

For example, add your current OptiTech branch to a starship prompt. Append this [custom.optitech] module to ~/.config/starship.toml. The command prints the pinned branch, and when hides the segment (exits non-zero) whenever you are not in a OptiTech project:

# ~/.config/starship.toml
[custom.optitech]
description = "Current OptiTech branch"
command = "optitech status --current-branch"   # prints the branch pinned in .optitech (no network)
when = "optitech status --current-branch"       # exits non-zero when no branch -> segment is hidden
symbol = "🌿 "
style = "bold green"
format = "[$symbol$output]($style) "

shell = ["sh"]
when = '''
d="$PWD"
while [ "$d" != "$HOME" ] && [ "$d" != / ]; do
  if [ -e "$d/.optitech" ]; then
    optitech status --current-branch >/dev/null 2>&1
    exit $?
  fi
  d=$(dirname "$d")
done
exit 1
'''

For a full copy-paste (and agent-ready) walkthrough, including prerequisites and troubleshooting, see this Starship + OptiTech branch setup gist.

optitech config plan

Shows what config apply would change, as a dry run. Nothing is modified.

optitech config plan [options]

optitech config plan --config ./optitech.ts --env .env.local

optitech config apply

Applies a optitech.ts policy to the branch.

optitech config apply [options]

For non-interactive use (scripts, CI, agents), pass --update-existing and --allow-protected to auto-confirm the corresponding prompts.

optitech config apply --branch feature/auth --update-existing --allow-protected