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
Section titled “Output”edka deployments list --all --json --no-inputedka 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--queryparameters for the next. - Progress, prompts and errors go to stderr, so stdout stays clean for a pipe.
- Tables show the useful columns.
--jsonprints the full records. --output rawprints the response body exactly as the API sent it.
Exit codes and errors
Section titled “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.
Without --json, an error from the API lists each invalid field under Edka’s
message, then the request ID:
Error: Check the highlighted fields (HTTP 400) namespace: This namespace does not existRequest ID: bfaa7377cb42446c4741608e001e6ac1With --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
Section titled “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
Section titled “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.
The sign-in is bound to that machine’s security chip, so its credentials don’t
work when copied to another machine or into a CI secret. Edka issues no
long-lived machine-to-machine tokens.
A GitHub Actions workflow signs in with a trust instead, and stores no secret.
With EDKA_TRUST set to the trust’s ID in a job that has
permissions: id-token: write, each command exchanges the OIDC token GitHub
gives the job for an access token, and exchanges a new one before it expires. A
trust can publish one custom app and update its installed instances. See
Sign in from GitHub Actions.
Without a terminal, a sensitive action that needs step-up verification doesn’t
wait for you. Run edka verify and confirm with your passkey first. For the
next 5 minutes, commands from that sign-in pass the check. A trust never
passes one.
Coding agents
Section titled “Coding agents”The CLI has two agent skills for coding agents such as Claude Code.
The edka skill,
skills/edka,
shows the agent how to use edka. It has the agent run edka context to check
which cluster and deployment a command acts on, start with diagnose when
something fails, and preview a change with --diff or --dry-run before
sending it. The agent treats a confirmation error as a question for you, and
reruns with --yes only after you agree. Secret values go on stdin, never on
the command line. The skill’s references list every command with its flags and
examples.
The edka-app skill,
skills/edka-app,
shows the agent how to package an application as a
custom app, validate and publish it, and install it
on a cluster.
For an agent that only investigates, sign in to a separate profile with read
access only. Edka refuses changes made with that sign-in. Have the agent pass
--profile readonly, or set EDKA_PROFILE=readonly in its environment:
edka login --profile readonly --read-onlyInstall the skills
Section titled “Install the skills”edka skill installedka skill install writes the skills that match your version of the CLI for
each coding agent it finds on your machine, into the skills directory that agent
reads. It finds an agent by its settings directory, such as ~/.claude or
~/.cursor. Agents that read the same directory share one copy, so Codex and
Cline get one in ~/.agents/skills. With no agent found, the install is for
Claude Code and Codex, and says so.
| Agent | --agent | Settings directory | Skills directory | With --project |
|---|---|---|---|---|
| Claude Code | claude-code | ~/.claude | ~/.claude/skills | .claude/skills |
| Codex | codex | ~/.codex | ~/.agents/skills | .agents/skills |
| Cursor | cursor | ~/.cursor | ~/.cursor/skills | .agents/skills |
| Gemini CLI | gemini-cli | ~/.gemini | ~/.gemini/skills | .agents/skills |
| GitHub Copilot | github-copilot | ~/.copilot | ~/.copilot/skills | .agents/skills |
| OpenCode | opencode | ~/.config/opencode | ~/.config/opencode/skills | .agents/skills |
| Windsurf | windsurf | ~/.codeium/windsurf | ~/.codeium/windsurf/skills | .windsurf/skills |
| Amp | amp | ~/.config/amp | ~/.config/agents/skills | .agents/skills |
| Goose | goose | ~/.config/goose | ~/.config/goose/skills | .goose/skills |
| Droid | droid | ~/.factory | ~/.factory/skills | .agents/skills |
| Kiro CLI | kiro-cli | ~/.kiro | ~/.kiro/skills | .kiro/skills |
| Cline | cline | ~/.cline | ~/.agents/skills | .agents/skills |
| Roo Code | roo | ~/.roo | ~/.roo/skills | .roo/skills |
| Junie | junie | ~/.junie | ~/.junie/skills | .junie/skills |
| Qwen Code | qwen-code | ~/.qwen | ~/.qwen/skills | .qwen/skills |
| Hermes Agent | hermes-agent | ~/.hermes | ~/.hermes/skills | .hermes/skills |
With CLAUDE_CONFIG_DIR set, Claude Code’s settings directory is
$CLAUDE_CONFIG_DIR and its skills go in $CLAUDE_CONFIG_DIR/skills.
HERMES_HOME does the same for Hermes Agent. CODEX_HOME changes where the
install looks for Codex, and XDG_CONFIG_HOME takes the place of ~/.config
for OpenCode, Amp and Goose.
--agent installs for the agents you name, found or not:
edka skill install --agent claude-code,cursorName a skill to install only that one:
edka skill install edka-app--project writes the skills to the agents’ directories at the root of the
current Git repository, the last column of the table, to commit them with the
project. --dir writes them to one directory you name, and can’t be combined
with --agent or --project:
edka skill install --projectedka skill install --dir ./skillsEach directory gets its own copy of a skill, not a link. With --json, stdout
holds the version and a directories list. Each entry has the directory’s
path, the agents that read it, and its skills, with each skill’s name,
path, the files the install wrote and the ones it removed.
Each skill directory also gets .edka-skill.json, the list of files the install
wrote. The next install reads it and replaces those files without asking, so
keep it with the skill, and commit it with --project. When a skill directory
holds a file the CLI didn’t write or a file you changed, or when it is a link,
the install asks first. It asks every question before it writes a skill, so
declining one leaves every skill as it was. Without a terminal it fails until
you rerun with --yes.
Keep the skills up to date
Section titled “Keep the skills up to date”After an upgrade, the new release rewrites each skill that edka skill install
wrote to a skills directory in your home, the fourth column of the table, when
no file in it changed after the install. edka upgrade prints ✓ Refreshed
with the skills it rewrote in each directory. It keeps a skill with changed
files, or a link, and prints why on stderr with the command that replaces it.
An upgrade adds no skill you didn’t install. With --json, the skills field
lists each skill’s name, path, whether it was refreshed, and the reason
the upgrade kept it.
For skills you installed with --project or --dir, run the install again
after an upgrade, with the same skill names and flags. Do the same after
brew upgrade edka, since Homebrew replaces the binary and leaves the skills as
they were.
With the skills CLI
Section titled “With the skills CLI”npx skills add edkadigital/cli offers both skills from the CLI’s repository
with the skills CLI. Its --agent
takes the same agent names. edka upgrade leaves skills installed that way
alone.
Profiles
Section titled “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 workedka login --profile personaledka profile listedka profile use work # The default profileedka whoami --profile personalThe profile without a name is default.
To remove a profile, sign out of it first:
edka logout --profile personaledka profile remove personaldefault 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
Section titled “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 --jsonSuggested commands
Section titled “Suggested commands”The commands the CLI suggests in Next: lines and in errors repeat the
--profile, --api-url, --organization, --cluster, --deployment and
--credential-store flags you passed, so they act on the same resources. A
suggestion about an add-on, an app, a cronjob, a database or a domain names the
cluster it is in, as in edka addons get keel --cluster production. Without
--cluster, that command looks in every cluster.
Keep the context in a script
Section titled “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.shedka run --kubeconfig -- kubectl get pods -AWith --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
Section titled “Environment variables”| Variable | Purpose |
|---|---|
EDKA_TRUST | ID of a trust a GitHub Actions job signs in with |
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_CLOUDFLARE_API_TOKEN | Cloudflare API token for edka domains |
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
Section titled “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 --debugdebug: 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
Section titled “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. Each
sign-in is bound to a key in the computer’s security chip, as the
CLI overview describes.
edka logout revokes the sign-in, then deletes the saved credentials.
edka logout --local deletes them without contacting Edka.