CLI configuration

The CLI connects to clusters through named contexts, mirroring the model used by kubectl. A context bundles a cluster URL with its authentication and TLS settings, and you select which one is active. This page covers creating contexts, where the config lives, how credentials are resolved, and the available authentication and TLS options.

Create and select a context

Define a context, then mark it as the current one:

lucenia config set-context local \
  --url http://localhost:9200 \
  --auth-type basic --username admin

lucenia config use-context local

Useful context management commands:

lucenia config contexts            # list defined contexts
lucenia config current-context     # show the active context
lucenia config view                # print the resolved config
lucenia config use-context prod    # switch the active context
lucenia config delete-context old  # remove a context

Config file location

The config lives at $XDG_CONFIG_HOME/lucenia/config.yaml, falling back to ~/.lucenia/config.yaml. It's created with 0600 permissions — keep those restrictive if you ever store a password directly.

A config file looks like this:

apiVersion: lucenia.dev/v1
kind: Config
current-context: local
contexts:
  local:
    url: http://localhost:9200
    auth:
      type: basic
      username: admin

Credential precedence

Every connection setting is resolved through a strict precedence chain, so you can keep secrets out of the config file when you need to:

flags > environment variables > selected context (-c) > current-context > built-in defaults

This means a --password flag always wins over LUCENIA_PASSWORD, which in turn wins over anything saved in the active context. The recognized environment variables are:

Variable	Overrides
LUCENIA_URL	Cluster URL
LUCENIA_USERNAME	Basic-auth username
LUCENIA_PASSWORD	Basic-auth password
LUCENIA_CONTEXT	Active context (same as -c)
LUCENIA_OUTPUT	Output format (same as -o)
LUCENIA_CONFIG	Path to the config file

Authentication

The CLI supports two auth types: none (the default) and basic (HTTP Basic). Pick the approach that fits your environment.

Anonymous (auth.type: none)

The default. No authentication header is sent — this is what a local HTTP-only development cluster expects.

lucenia config set-context local --url http://localhost:9200
lucenia config use-context local
lucenia ping

Basic auth from the environment (recommended for CI)

Store the username in the context and pass the password through the environment, so nothing sensitive lands on disk:

lucenia config set-context prod \
  --url https://lucenia.prod.internal \
  --auth-type basic --username admin

LUCENIA_PASSWORD='…' lucenia -c prod cluster health

Basic auth from a password helper (recommended for dev)

password_command runs an external helper (op, pass, vault, …) at request time and uses its stdout as the password. config set-context doesn't write this field yet, so edit the config file directly:

apiVersion: lucenia.dev/v1
kind: Config
current-context: prod
contexts:
  prod:
    url: https://lucenia.prod.internal
    auth:
      type: basic
      username: admin
      password_command: [op, read, "op://Lucenia/prod/password"]

Basic auth at the command line

For a one-off invocation against a context you haven't saved — or to temporarily override a saved context — pass credentials as flags. Because flags win over everything else, this also overrides the active context:

lucenia --url https://lucenia.example.com \
        --user admin --password 'hunter2' \
        ping

warning

Passing --password on the command line exposes the secret to your shell history and process listings. Prefer the environment-variable or password-helper approaches outside of throwaway local testing.

TLS

Two transport-level knobs live under tls: on each context:

• tls.ca_cert (or config set-context --ca-cert) pins a CA bundle for servers presenting a private certificate.
• tls.insecure_skip_verify (or the persistent --insecure-skip-verify flag) disables certificate verification entirely.

# Trust a private CA
lucenia config set-context prod \
  --url https://lucenia.prod.internal \
  --auth-type basic --username admin \
  --ca-cert /etc/lucenia/root-ca.pem

warning

--insecure-skip-verify turns off TLS verification and should only be used for local clusters with self-signed certificates — never in production. Pin a CA bundle with --ca-cert instead.

Next steps

With a context configured, head to CLI usage to run commands against your cluster.