CLI configuration

The maqpna CLI config file and contexts, where login tokens are stored, and which of flags, environment and config wins.

The maqpna CLI keeps one small YAML file with named contexts. A context says which installation a command talks to: the gateway URL, the Kubernetes cluster and the default namespace. Use contexts when you work with more than one installation, such as a local MAQPNA and a production cluster, so you do not have to repeat --gateway and --kubeconfig on every command.

The maqpna-install plugin (install, upgrade, rollback, uninstall, preflight), maqpna console and maqpna desk read the same file.

File location#

The CLI looks for the file in this order:

1. $MAQPNA_CONFIG, when it is set.
2. $XDG_CONFIG_HOME/maqpna/config.yaml, when XDG_CONFIG_HOME is set.
3. <home>/.config/maqpna/config.yaml.

The same rule applies on every OS. The CLI does not use ~/Library on macOS or %APPDATA% on Windows.

Login tokens are stored next to the file, in tokens/<context>.json. See Credentials storage.

A missing file is not an error: the CLI then works from flags and environment variables alone. The CLI creates the file the first time you run maqpna context set or maqpna login. It writes it atomically, with mode 0600 in a directory with mode 0700.

File format#

The file is YAML. Parsing is strict: an unknown key is an error, so a typo does not go unnoticed.

currentContext: prod
contexts:
  dev:
    gateway: http://127.0.0.1:8080
  prod:
    gateway: https://gateway.example.eu
    identity: https://identity.example.eu
    attest: https://attest.example.eu
    kubeconfig: /home/alice/.kube/prod-eu.yaml
    kubeContext: prod-eu
    namespace: team-a
    operatorNamespace: maqpna-system

The file holds no secrets. Do not put tokens in it.

Top-level keys#

Context names use letters, digits, ., _ and -, start with a letter or digit, and are at most 63 characters long.

Context keys#

Set up contexts#

Step 1: Create a context#

maqpna context set prod --gateway https://gateway.example.eu --kube-context prod-eu --namespace team-a --use

context "prod" created in /home/alice/.config/maqpna/config.yaml

--use also makes it the current context. The first context you create becomes the current context even without --use. To store a kubeconfig path, pass the global --kubeconfig FILE with context set. To clear a key, pass - as its value, for example --namespace -.

Step 2: Add a second context and switch#

maqpna context set dev --gateway http://127.0.0.1:8080
maqpna context use dev

context "dev" created in /home/alice/.config/maqpna/config.yaml
switched to context "dev"

Step 3: Check it worked#

maqpna context list

CURRENT  NAME  GATEWAY                     KUBE-CONTEXT  NAMESPACE  LOGGED-IN
*        dev   http://127.0.0.1:8080       -             -          no
         prod  https://gateway.example.eu  prod-eu       team-a     no

LOGGED-IN shows whether a login token is stored for the context. To see the file itself, run maqpna config view. Add --minify to show only the current context.

Step 4: Use a context for one command#

Pass --context or set MAQPNA_CONTEXT. Neither changes currentContext.

maqpna --context prod get agents
MAQPNA_CONTEXT=prod maqpna get agents

Step 5: Log in#

maqpna --context prod login

maqpna login gets the OIDC issuer, client ID and scopes from the gateway (GET /v1/auth/config), runs the browser flow (or the device flow with --device), checks the token with GET /v1/whoami and stores it for the context. It also writes the gateway URL into the context. Without --context or MAQPNA_CONTEXT, it uses the current context, or creates a context named default.

Check who you are:

maqpna whoami

Context commands#

For kubectl users, maqpna config has the familiar aliases:

All of them take -o table|json|yaml and --jq EXPR.

Credentials storage#

maqpna login stores the token of each context in tokens/<context>.json, in the same directory as the config file (for example ~/.config/maqpna/tokens/prod.json). The CLI does not use the OS keychain.

• The file is written atomically with mode 0600, in a directory with mode 0700.
• On macOS and Linux, the CLI refuses a token file that group or other users can read or write. Fix it with chmod 600 <file>, or log in again.
• The file holds the access token, and for OIDC logins the refresh token, ID token, expiry, issuer, client ID, token endpoint and scopes. type is oidc for a browser or device login, or static for maqpna login --with-token.
• The file records the gateway the token was issued for. The CLI does not send the token to a gateway on another host, except a loopback address (a port-forward). To allow it, pass --allow-gateway-mismatch or set MAQPNA_ALLOW_GATEWAY_MISMATCH=1.
• An expired OIDC token is refreshed with the refresh token, when the identity provider issued one.
• maqpna logout and maqpna context delete delete the token file.

Precedence#

Each setting is taken from the first source that has a value, from left to right.

flowchart LR
    F["Command flag<br/>(after the command)"] --> G["Global flag<br/>(before the command)"]
    G --> E["Environment variable"]
    E --> C["Selected context<br/>in config.yaml"]
    C --> D["Built-in default"]

Not every setting has every source. The exact order per setting:

The admin-API token follows its own order:

flowchart TD
    A{"--oidc-token-file or<br/>MAQPNA_OIDC_TOKEN_FILE set?"} -->|yes| A1["Read the token from that file"]
    A -->|no| B{"--token or<br/>MAQPNA_ADMIN_TOKEN set?"}
    B -->|yes| B1["Use the static token"]
    B -->|no| C{"Context has<br/>oidcTokenFile?"}
    C -->|yes| C1["Read the token from that file"]
    C -->|no| D{"tokens/CONTEXT.json<br/>stored?"}
    D -->|yes| D1["Use it (refresh if expired)"]
    D -->|no| E1["Send no token"]

A flag always wins over its environment variable, because the variable only sets the flag's default.

Where global flags go#

Global flags go before the command name: maqpna --context prod get agents. After the command name, only --context, --kubeconfig, -o/--output and --jq are global; --gateway and -n there are the command's own flags. An unknown flag before the command is an error:

$ maqpna --namespce team-a get agents

The CLI suggests the closest global flag and reminds you that command flags go after the command name.

What can go wrong#

Next steps#

• Environment variables: every variable the CLI and the servers read.
• maqpna login: login flags and flows.
• The CLI architecture: how the CLI and its plugin fit together.
• Set up your dev environment: local MAQPNA and a dev context.
• MAQPNA for kubectl users: the kubectl-style commands.