Scripts and CI

Every command of the Edka CLI works without a terminal. It prints JSON with --json, never prompts in CI, and exits with a code a script can test. This page covers what scripts, CI jobs and coding agents rely on, and how profiles and directory links decide which account and cluster a command acts on.

Output

edka deployments list --all --json --no-input
edka api get /api/deployments --json | jq '.data[].id'
edka clusters delete staging --yes --json

• With --json, stdout holds only the result, as JSON. A list keeps the API’s envelope, {"data": [...]}, with its pagination fields. A command returns one page of results; endpoints that page take --query parameters for the next.
• Progress, prompts and errors go to stderr, so stdout stays clean for a pipe.
• Tables show the useful columns. --json prints the full records.
• --output raw prints the response body exactly as the API sent it.

Exit codes and errors

Code	Meaning
0	The command succeeded.
1	The command failed, or a diagnose found a problem.
130	The command was interrupted with Ctrl+C or SIGTERM.

edka run exits with the code of the command it ran.

With --json, an error is a JSON object on stderr, with error and exit_code. An error from the API adds status and request_id, and code, reason, details and fields when the API sent them. Each entry of fields names an invalid field and its message:

{
    "error": "…",
    "exit_code": 1,
    "status": 400,
    "request_id": "…",
    "fields": [{ "field": "replicas", "message": "…" }]
}

Prompts and confirmations

A command that deletes, replaces or revokes something asks for confirmation in a terminal. Deleting a cluster or a database asks you to type its name. In a script, pass --yes to confirm.

The CLI never prompts with --no-input, EDKA_NO_INPUT=1, or in CI, where the CI variable is set. A confirmation then fails with an error that asks you to rerun with --yes. A script gets no picker either, so name each resource. A name that matches more than one resource fails with an error that lists their IDs.

The CLI never retries a change on its own, so a response that times out doesn’t create a resource twice. The one exception is edka env set and edka env unset, which send a change again, up to three times, when Edka refused it because the deployment changed after they read it. A --wait keeps reading when Edka can’t be reached, and stops with the error after two minutes of failed reads.

Authentication in automation

edka login needs a browser and a terminal. A saved sign-in on a machine you control refreshes itself, so scripts and agents on that machine keep working.

EDKA_TOKEN takes an access token issued to the Edka CLI. The CLI uses it for every command, and never saves or refreshes it. Access tokens expire after 15 minutes, and Edka issues no long-lived machine-to-machine tokens.

Profiles

A profile is a saved sign-in: an API address, an organization and its credentials. Each sign-in is bound to one organization, so use a profile per organization:

edka login --profile work
edka login --profile personal
edka profile list
edka profile use work                    # The default profile
edka whoami --profile personal

The profile without a name is default.

To remove a profile, sign out of it first:

edka logout --profile personal
edka profile remove personal

default always exists, so removing it resets it to https://api.edka.io. Removing the profile that edka profile use picked switches back to default.

Which cluster a command uses

A command takes each part of its context from the first place that sets it:

Setting	Flag	Variable	Then
Profile	--profile	EDKA_PROFILE	the directory link, then the default profile
API address	--api-url	EDKA_API_URL	the profile, then https://api.edka.io
Organization	--organization	EDKA_ORGANIZATION	the directory link, then the profile
Cluster	--cluster	EDKA_CLUSTER	the directory link, then the profile’s default
Deployment	--deployment	EDKA_DEPLOYMENT	the directory link

A directory link applies only when its profile and API address match the command’s. edka context prints what a command in the current directory would use:

edka context --json

Keep the context in a script

edka run starts a command with EDKA_PROFILE, EDKA_API_URL, EDKA_ORGANIZATION, EDKA_CLUSTER and EDKA_DEPLOYMENT set to the current context. edka commands inside it read those variables ahead of the directory link, so a script keeps its target after it changes directory:

edka run --cluster staging -- ./scripts/release.sh
edka run --kubeconfig -- kubectl get pods -A

With --kubeconfig, run also sets KUBECONFIG to a private file with your own kubeconfig for the cluster, which expires after an hour, and deletes the file when the command exits. run passes no API token or application secrets. Ctrl+C and SIGTERM reach the command, and run waits for it to exit.

Environment variables

Variable	Purpose
EDKA_TOKEN	Access token for the CLI, never saved
EDKA_PROFILE	Profile to use
EDKA_API_URL	API address. HTTPS, except for a loopback address
EDKA_ORGANIZATION	ID of the organization
EDKA_CLUSTER	Cluster ID or name
EDKA_DEPLOYMENT	Deployment ID or name
EDKA_CONFIG_DIR	Directory of the configuration
EDKA_CREDENTIAL_STORE	auto, keyring or file
EDKA_NO_INPUT	Never prompt, like --no-input
EDKA_DEBUG	Print each request to stderr, like --debug
EDKA_NO_UPDATE_CHECK	Never look for a newer release
NO_COLOR	No colors and no progress animation
CI	No prompts and no lookup of a newer release

0 or false turns EDKA_NO_INPUT, EDKA_DEBUG and EDKA_NO_UPDATE_CHECK off. Without EDKA_CONFIG_DIR, the configuration lives in $XDG_CONFIG_HOME/edka, or in ~/.config/edka.

Debug requests

--debug prints a line to stderr for each request a command sends: the method and URL, then the status, the time in milliseconds and Edka’s request ID.

$ edka apps list --debug
debug: GET https://api.edka.io/api/clusters 200 143ms (request 484dd403-11fa-4d06-b1c3-8fcb5b2af4af)
debug: GET https://api.edka.io/api/clusters/35c0c473-e7d1-492e-af0d-170a78e0a8b3/apps/instances 200 96ms (request cfb1759c-7774-44a8-ba93-e6b77aaf4f1b)

The lines hold no header and no body, so no token and no secret. Include the request ID when you report a problem to Edka.

Credentials

Credentials go into the system keyring by default. When it isn’t available, --credential-store auto says so and falls back to private files, readable only by you. keyring fails instead of falling back, and file uses the files directly. The configuration and .edka.json never contain credentials.

edka logout revokes the sign-in, then deletes the saved credentials. edka logout --local deletes them without contacting Edka.