Profiles

Every command that talks to PineXQ needs an endpoint and an API key. The read and act commands need them, and so do deploy and register. Instead of passing them on every call, you can keep them in a global config file as named profiles. Each profile pairs one endpoint with one API key.

The global config file

The file lives at $XDG_CONFIG_HOME/pinexq/config.toml. When XDG_CONFIG_HOME is not set, that is ~/.config/pinexq/config.toml, on every operating system. You create and edit it by hand:

~/.config/pinexq/config.toml

default_profile = "dev"

[profiles.dev]
endpoint = "jobs.api.dev.pinexq.net"
api_key = "…"

[profiles.prod]
endpoint = "jobs.api.pinexq.net"
api_key = "…"

• default_profile names the profile to use when you don’t pick one. Leave it out and no profile is used unless you select one.
• [profiles.<name>] holds a profile’s endpoint and api_key. Both are optional. A missing value is taken from the next source in the order below.

An API key belongs to exactly one context, personal or organization. A profile therefore stands for one context on one PineXQ environment. Use one profile per combination you work with.

Caution

The file holds API keys in plain text. Make it readable only by you:

chmod 600 ~/.config/pinexq/config.toml

The CLI warns when other users can read it.

Selecting a profile

Pass --profile before the noun, or set PINEXQ_PROFILE:

pinexq --profile prod job list
PINEXQ_PROFILE=prod pinexq wd list

--profile is a global option. pinexq job list --profile prod does not work.

How a value is chosen

The endpoint and the API key are resolved separately. For each one, the first source that has a value wins:

1. the --endpoint / --api-key flags,
2. the PINEXQ_ENDPOINT / PINEXQ_API_KEY environment variables (a .env file in the working directory counts),
3. the profile selected with --profile or PINEXQ_PROFILE,
4. for the endpoint only, pinexq_endpoint in a pinexq.toml in the working directory,
5. the default profile.

So a profile you select explicitly overrides a project’s pinexq.toml, while the default profile never does. Inside a project that points at dev, this deploys to prod:

pinexq --profile prod deploy

Note

Inside a project, the endpoint can come from pinexq.toml while the API key comes from the default profile. If the two belong to different environments, the request fails with an authentication error. Select the matching profile with --profile, or make the default profile match the project.

Errors

• A profile name that doesn’t exist, whether from --profile or from default_profile, stops the command. The error lists the profiles that do exist.
• A config file that isn’t valid TOML, or has unknown keys or the wrong structure, stops the command with the reason.

In CI, keep using PINEXQ_ENDPOINT and PINEXQ_API_KEY (see CI usage); no config file is needed there.