SYS.DOCS // DOCS

Edka CLI

edka is the command line for Edka. It deploys, follows logs, diagnoses failures, and manages clusters, apps and databases from a terminal, a script or a coding agent. It calls the same API as the console, with the permissions of your role in the organization. The source is on GitHub.

$ edka login
Authorize Edka CLI in your browser
…
✓ Signed in to Acme as you@example.com
  Next: edka link

$ edka link --cluster production --deployment api
✓ Linked this directory
  Cluster: production
  Deployment: api
  Context: /home/you/api/.edka.json
  Next: edka status

$ edka up --wait
Deployment submitted. Waiting for generation 3…
Applying generation 3…
Rolling out: 1/2 updated, 2/2 ready
Rolling out: 2/2 updated, 2/2 ready
✓ api is running generation 3

Prerequisites

An Edka account. Sign up if you have none.
macOS, Linux or Windows, on amd64 or arm64.

Install

macOS and Linux

curl -fsSL https://edka.io/install.sh | sh

The script downloads the latest release for your system, checks it against the SHA-256 in the release’s checksums.txt, and puts edka in ~/.local/bin. When that directory isn’t on your PATH, it prints the line to add to ~/.zshrc or ~/.bashrc.

Homebrew

brew install edkadigital/tap/edka

Windows

In PowerShell:

irm https://edka.io/install.ps1 | iex

The script checks the download the same way, puts edka.exe in %LOCALAPPDATA%\Programs\edka, and adds that directory to your PATH. Terminals that were open before need a restart to find edka.

Go

With Go 1.26 or newer:

go install github.com/edkadigital/cli/cmd/edka@latest

go install puts edka in $(go env GOPATH)/bin, unless GOBIN is set.

Check the installation:

edka version

Install options

Both install scripts read these variables:

Variable	Sets
`EDKA_VERSION`	A release to install, such as `v1.2.3`, instead of the latest
`EDKA_INSTALL_DIR`	The directory of the binary. `install.ps1` then leaves `PATH` alone
`EDKA_RELEASES_URL`	A mirror of `https://github.com/edkadigital/cli/releases`

curl -fsSL https://edka.io/install.sh | EDKA_VERSION=v1.2.3 sh

Each release also has the archives, named edka_<version>_<os>_<arch>, for macOS (darwin), Linux and Windows on amd64 and arm64, and checksums.txt with the SHA-256 of each. To build from source, clone the repository and run make install. A binary built from source has the version dev, and edka upgrade leaves it alone.

Start the sign-in:
Terminal window
```
edka login
```
The browser opens Edka’s consent page. It shows your organization, your email, and the access the CLI asks for. Write access, to create, deploy, update and delete, is optional. Untick it, or run edka login --read-only, to give the CLI read access only.
Select Authorize. The terminal prints the organization and the email you signed in with.
Check who you are signed in as:
Terminal window
```
edka whoami
```

The CLI acts with your role in the organization, and the cluster permissions of your account apply to every request. A sign-in is bound to one organization. To work in another one, select it in the console and sign in again with a separate profile, as Scripts and CI describes.

Credentials go into the system keyring: Keychain on macOS, Credential Manager on Windows, and the Secret Service on Linux. edka logout revokes them and deletes them. To revoke a sign-in from another computer, open Settings > Security in the console and select Revoke next to the Edka CLI under Authorized applications.

edka login --no-browser prints the authorization URL instead of opening it. The browser then has to reach the CLI’s callback on the server, which listens on 127.0.0.1 only, so forward the port over SSH:

On your computer, connect with a port forward:
Terminal window
```
ssh -L 43871:127.0.0.1:43871 you@server
```
On the server, start the sign-in on that port:
Terminal window
```
edka login --no-browser --callback-port 43871
```
Open the printed URL in your browser and select Authorize.

The CLI waits five minutes for the authorization.

Link a project directory

A link saves a cluster, and optionally a deployment, for the commands you run in a directory. edka logs, edka up and the other commands then need no --cluster or --deployment.

In the project directory, run:
Terminal window
```
edka link
```
A picker lists your clusters. Press / to filter the list, and Enter to choose. A second picker lists the deployments of that cluster. Choose Cluster only to link the cluster alone.
Check the link:
Terminal window
```
edka status
```
status shows the linked deployment with its replicas and pods, or the linked cluster.

To link without a picker, name the cluster and the deployment:

edka link --cluster production --deployment api

link writes .edka.json with the IDs of the cluster and the deployment, the profile and the API address. It holds no credentials. Commands find the nearest .edka.json in the current directory or its parents, up to the root of the Git repository. Add it to .gitignore to keep it out of the repository. edka unlink removes it.

Upgrade

edka upgrade

upgrade downloads the latest release for your system, checks it against the release’s checksums.txt, and replaces the binary. A download that doesn’t match replaces nothing. edka upgrade --check reports the latest release and installs nothing.

A binary from Homebrew is Homebrew’s to replace, so upgrade it with brew upgrade edka. edka upgrade names that command and replaces nothing.

Once a day, while a command runs in a terminal, the CLI looks for a newer release and prints a notice after the output, with the command that installs it. The lookup sends no token and installs nothing. It doesn’t run in CI, in scripts, or with EDKA_NO_UPDATE_CHECK=1.

Shell completion

Tab completes commands, flags, and the names of clusters, deployments, databases, cron jobs, apps, add-ons and profiles.

# zsh: add ~/.zsh/completions to fpath before compinit
mkdir -p ~/.zsh/completions
edka completion zsh > ~/.zsh/completions/_edka

# bash
source <(edka completion bash)

# fish
edka completion fish > ~/.config/fish/completions/edka.fish

Commands

edka --help lists every command, and edka <command> --help shows its flags and examples.

Task	Commands	Page
Deploy, read logs, change variables	`up`, `build`, `logs`, `env`, `restart`, `scale`, `rollback`	Deploy from the terminal
Find out why something fails	`diagnose`, `doctor`	Diagnose problems
Create clusters, node pools, domains	`clusters`, `nodepools`, `domains`, `registries`, `secrets`	Clusters and infrastructure
Install apps and add-ons	`apps`, `addons`	Apps and add-ons
Back up databases, run cron jobs	`databases`, `cronjobs`	Databases and cron jobs
Call any endpoint of the API	`api`	API commands
Script, run in CI, switch accounts	`--json`, `profile`, `run`, `context`	Scripts and CI

Troubleshooting

Something doesn’t work and the error doesn’t say why. Run edka doctor. It checks the configuration and profile, the project link, the API and its sign-in discovery, your identity, and the cluster in context, and prints the reason for each check that fails.

macOS refuses to open edka. A browser marks a file it downloads as quarantined, and tar passes the mark on to edka. macOS then blocks the binary, which isn’t notarized. Remove the mark from the binary you unpacked:

xattr -d com.apple.quarantine ~/.local/bin/edka

The install script and Homebrew download without the mark.

The keyring isn’t available. On a Linux server without the Secret Service, the CLI says it falls back to private files, readable only by you. --credential-store keyring fails instead of falling back, and --credential-store file uses the files directly.

browser login needs a terminal. edka login runs only in an interactive terminal. See Scripts and CI for automation.