pks configuration and state reference

pks keeps every piece of durable state in one directory tree under your home folder, plus a small per-repository folder. Nothing is written to a system-wide location, no database is involved, and no state lives in a registry hive or a keychain.

Synopsis

pks <command> [options]

The configuration root and its contents:

~/.pks-cli/
  settings.json              global key/value config and most OAuth tokens
  agentics-auth.json         Keycloak tokens from `pks agentics init`
  actions.json               two-factor action policy
  runners.json               GitHub runner registrations
  agentics-runners.json      Agentics runner registrations
  firecracker-runners.json   Firecracker runner registrations
  registries.json            container/package registry config
  coolify.json               Coolify endpoint config
  claude-marketplace.json    Claude plugin marketplace config
  ssh-targets.json           named SSH targets
  rsync-targets.json         named rsync targets
  vms.json                   VM metadata store
  models.json                local model registry
  ado-credentials.json       Azure DevOps git-proxy credentials
  foundry-token-cache.json   cross-process Foundry token cache
  certs/                     code-signing certificates (encrypted)
  ssh-keys/                  pks-held SSH private keys (encrypted)
  share/                     Agent Share logins (encrypted refresh token)
  keys/                      generated VM SSH keypairs
  brain/                     Brain firehose store
  writing/                   global writing-profile layer
  models/                    downloaded local models
  usage-cache/               Claude usage cache
  agent-skills/              coding-agent skill files
  firecracker/               Firecracker runner assets
  vscode/                    VS Code CLI assets for devcontainer spawn
  logs/                      devcontainer spawn and install logs

Configuration root

The root is resolved from the current user's profile directory and is hardcoded on every platform. There is no PKS_HOME, no PKS_CONFIG, and no XDG override for it.

On Windows the root is under %USERPROFILE%, not %APPDATA%, so it does not follow a roaming profile.

Global state files

Every path below is relative to the configuration root.

Project-local state

These paths live in the repository you run pks from, not in your home directory. The .pks project folder and the ~/.pks-cli home folder are separate things, and both are load-bearing.

Global options

These four flags are parsed against raw arguments before the command parser runs, so they take effect anywhere on the command line.

--verbose is not global. It is a per-command option on the commands that define it, such as pks github status --verbose.

Banner suppression

The banner is suppressed by an allowlist, not by a general rule, so a command that pipes cleanly today is one that appears in that list. Suppression applies to: pks mcp in stdio transport, pks git askpass, pks foundry proxy, pks ado git-proxy, pks claude limits, pks claude session-usage, all pks hooks event commands and pks hooks with --json, pks writing prompt|accept, pks writing naturalness prompt|accept|patterns, pks persona prompt|accept|show, pks persona list --json, pks persona lint --json, and pks ssh run|copy.

Environment variables

Every variable below is read by the CLI. Variables that pks only writes into child processes are listed separately in "Variables pks sets for child processes".

Agentics server and runners

GitHub Actions context

AI providers and agent runtimes

Telemetry export

Tracing and metrics activate only when an OTLP endpoint is configured. With no endpoint set, no telemetry leaves the process.

pks internals

External binaries and host lookups

Terminal and host environment

Note. The pks hooks event commands and the system information report enumerate the entire environment rather than named variables. Treat any secret exported into the shell as visible to those code paths.

Variables pks sets for child processes

pks exports these into runners, job containers, and spawned tools. It does not read them back.

PKS_RUNNER, PKS_TOKEN_URL, PKS_DISCOVERY, PKS_CODEX_TOKEN, PKS_CODEX_FOUNDRY_API_KEY, COOLIFY_APP_FQDN, COOLIFY_ENVIRONMENT, HEYPOUL_ENDPOINT, HEYPOUL_TOKEN, HEYPOUL_API_KEY, HEYPOUL_LANGUAGE, and DOCKER_BUILDKIT.

Credential storage

pks stores credentials on the filesystem. There is no operating-system keychain, no Windows data-protection API, and no hardware-backed key. Two tiers exist.

Tier A — file-encrypted stores

Code-signing certificates, pks-held SSH private keys, and Agent Share refresh tokens are sealed with AES-GCM using a 256-bit key and a 128-bit tag. Each blob is nonce || tag || ciphertext. The key-encryption key is a 32-byte random file created on first use and written next to the directory it protects: .certs-kek, .ssh-keys-kek, and .share-kek.

This is resistance to casual reading, not confidentiality against a local attacker. The key sits in the same home directory as the ciphertext, with no passphrase and no external key store, so any process running as you can decrypt these files.

On Linux and macOS these files are set to owner-only permissions — 0600 for files, 0700 for directories, best effort. On Windows every one of those hardening calls is a deliberate no-op, so the files carry whatever the profile directory grants.

Tier B — plaintext settings

settings.json is the shared key/value store, and most provider credentials land in it as plaintext JSON. It is written with an ordinary file write and does not get the owner-only permission treatment applied to the Tier A stores.

Credential keys written there:

• azure.auth.credentials — Azure Resource Manager tokens.
• ado.auth.credentials — Azure DevOps tokens.
• foundry.auth.credentials — Azure AI Foundry tokens.
• fileshare.azure.credentials — Azure Files credentials.
• msgraph.auth.token and msgraph.auth.config — Microsoft Graph token and client configuration.
• scaleway.auth.credentials — Scaleway access and secret key.
• tailscale.auth.credentials — Tailscale credentials.
• google:api_key — Google AI API key.
• jira:api_token — Atlassian API token.
• The GitHub token, under a per-user key.

Two non-credential keys share the file: telemetry.enabled and cli.first-time-warning-acknowledged.

Note. The internal configuration API takes an encrypt parameter that does not encrypt. When set, it replaces the value with the literal string ***encrypted***, discarding the input. Every credential path in the CLI leaves it off.

The store also seeds hardcoded demo defaults at startup — cluster.endpoint, namespace.default, registry.url, auth.token, deploy.replicas, and monitoring.enabled. These are placeholder values, not live configuration, and pks has no Kubernetes deployment feature behind them. There is no top-level pks config command; the only registered configuration command is pks jira config.

Authentication flows

Every provider follows the same command shape: pks <provider> init starts the login, and pks <provider> status reports what is stored. There is no pks auth command and no pks logout.

Loopback flows print the authorization URL before opening a browser, so they work over SSH. Set BROWSER to control which command opens it.

In GitHub Actions, pks agentics needs no stored login. Its token resolution runs in order: an explicit --token, then the GitHub Actions OIDC exchange, then the stored Keycloak token from agentics-auth.json (refreshed in place with a 30-second clock skew when expired), then a stored runner registration token.

Job containers receive a short-lived token over a unix socket credential server rather than a copy of your credentials. PKS_TOKEN and PKS_TOKEN_URL point pks sign at that server.

Sensitive actions can require a TOTP code before they run. pks authenticator enrolls the factor and pks actions chooses which operations are gated. Before a factor is enrolled, gated actions pass silently.

Logging and diagnostics

Log levels are fixed at startup and no environment variable changes them. Console logging runs at warning level and above. For pks mcp in stdio transport and pks foundry proxy the console sink is removed entirely and the level is raised to error, so the protocol stream on stdout stays clean.

--debug is the one global verbosity switch. It sets PKS_DEBUG=1, which the devcontainer and VM code paths read.

The command telemetry, session data, and interaction services are in-memory only. They hold bounded queues and dictionaries, write nothing to disk, and open no network connection — pks does not send usage data anywhere. telemetry.enabled in settings.json gates the in-memory collection and is treated as on unless it is explicitly false.

Log files that are written:

Redaction is not general. Only the Jira debug writer redacts basic-authentication parameters and truncates bearer tokens. Treat other debug output as potentially containing secrets before pasting it into an issue.

Inspecting and resetting state

Read the current state with the per-provider status commands, which report what is stored without printing secrets:

pks github status --verbose    # GitHub token and git:push capability
pks foundry status             # Foundry login and selected model
pks ado status                 # Azure DevOps organization and login
pks vm status                  # VM metadata store
pks authenticator status       # whether a TOTP factor is enrolled

There is no logout command and no reset command. Removing a credential means removing its file or its key. Deleting a whole provider's state is a file operation:

rm ~/.pks-cli/agentics-auth.json    # forget the Agentics login
rm -rf ~/.pks-cli/share             # forget every Agent Share login

Re-running the matching init command restores the login.

Do not commit. The .pks/ folder in a repository is project configuration and is safe to commit. Everything under ~/.pks-cli/ is credential material and must stay out of version control, including the .certs-kek, .ssh-keys-kek, and .share-kek files, which are the keys to the encrypted stores.

Removing ~/.pks-cli entirely resets the CLI to a first-run state. That also deletes generated VM SSH keypairs, pks-held signing certificates, and the Brain store, none of which can be recovered from the remote side.

See also

• pks — the command surface and how the families fit together
• pks agentics — the Keycloak login and runner registration this page's tokens belong to
• pks github — the device-code login and the runner it authorizes
• pks actions — choosing which operations require a two-factor code
• pks authenticator — enrolling the TOTP factor that makes the gate live
• pks update — how pks detects its install method and upgrades itself