Skip to content
SYS.DOCS // DOCS

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.

Terminal window
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.
CodeMeaning
0The command succeeded.
1The command failed, or a diagnose found a problem.
130The 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 exist
Request ID: bfaa7377cb42446c4741608e001e6ac1

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": "…" }]
}

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.

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.

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:

Terminal window
edka login --profile readonly --read-only
Terminal window
edka skill install

edka 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--agentSettings directorySkills directoryWith --project
Claude Codeclaude-code~/.claude~/.claude/skills.claude/skills
Codexcodex~/.codex~/.agents/skills.agents/skills
Cursorcursor~/.cursor~/.cursor/skills.agents/skills
Gemini CLIgemini-cli~/.gemini~/.gemini/skills.agents/skills
GitHub Copilotgithub-copilot~/.copilot~/.copilot/skills.agents/skills
OpenCodeopencode~/.config/opencode~/.config/opencode/skills.agents/skills
Windsurfwindsurf~/.codeium/windsurf~/.codeium/windsurf/skills.windsurf/skills
Ampamp~/.config/amp~/.config/agents/skills.agents/skills
Goosegoose~/.config/goose~/.config/goose/skills.goose/skills
Droiddroid~/.factory~/.factory/skills.agents/skills
Kiro CLIkiro-cli~/.kiro~/.kiro/skills.kiro/skills
Clinecline~/.cline~/.agents/skills.agents/skills
Roo Coderoo~/.roo~/.roo/skills.roo/skills
Juniejunie~/.junie~/.junie/skills.junie/skills
Qwen Codeqwen-code~/.qwen~/.qwen/skills.qwen/skills
Hermes Agenthermes-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:

Terminal window
edka skill install --agent claude-code,cursor

Name a skill to install only that one:

Terminal window
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:

Terminal window
edka skill install --project
edka skill install --dir ./skills

Each 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.

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.

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.

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:

Terminal window
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:

Terminal window
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.

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

SettingFlagVariableThen
Profile--profileEDKA_PROFILEthe directory link, then the default profile
API address--api-urlEDKA_API_URLthe profile, then https://api.edka.io
Organization--organizationEDKA_ORGANIZATIONthe directory link, then the profile
Cluster--clusterEDKA_CLUSTERthe directory link, then the profile’s default
Deployment--deploymentEDKA_DEPLOYMENTthe 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:

Terminal window
edka context --json

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.

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:

Terminal window
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.

VariablePurpose
EDKA_TRUSTID of a trust a GitHub Actions job signs in with
EDKA_PROFILEProfile to use
EDKA_API_URLAPI address. HTTPS, except for a loopback address
EDKA_ORGANIZATIONID of the organization
EDKA_CLUSTERCluster ID or name
EDKA_DEPLOYMENTDeployment ID or name
EDKA_CONFIG_DIRDirectory of the configuration
EDKA_CREDENTIAL_STOREauto, keyring or file
EDKA_CLOUDFLARE_API_TOKENCloudflare API token for edka domains
EDKA_NO_INPUTNever prompt, like --no-input
EDKA_DEBUGPrint each request to stderr, like --debug
EDKA_NO_UPDATE_CHECKNever look for a newer release
NO_COLORNo colors and no progress animation
CINo 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 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.

Terminal window
$ 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 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.