edgible application

Manage applications

edgible application list

Aliases: ls

List all configured applications

edgible application list [flags]

Flag	Description
--device <id>	Only applications assigned to this device
--status <status>	Only applications with this status (deployed, deploying, error, shutdown, unknown)
--limit <n>	Show at most n applications

Examples

edgible application list
edgible application list --device <serving-device-id>
edgible application list --status error          # only the broken ones
edgible application list --json | jq '.[].id'

edgible application create

Aliases: new

Create a new application (asks which kind if you do not say)

edgible application create [subtype] [flags]

Examples

edgible application create                       # asks which kind, then runs it
edgible application create existing              # a port already listening on a device
edgible application create docker-compose        # a compose file deployed to a device

By default, every create subcommand waits for the application to converge on its device — the same streaming phase output that stack deploy prints — and exits non-zero if convergence fails or times out. For an https app the wait ends with a certificate status line (issued, or validating — check with: edgible certs). Pass --no-wait to return as soon as the application is registered; the CLI then prints Application registered. Deploying — check progress with: edgible application get <name> and exits 0. --wait-timeout <seconds> (default 600) bounds the wait.

edgible application create existing

Create application for a port already listening on a serving device

edgible application create existing [flags]

Flag	Description
-n, --name <name>	Application name
-d, --description <description>	Application description
-p, --port <port>	Port already listening on the serving device (prompted if omitted; required with —non-interactive)
--protocol <protocol>	Protocol (http, https, tcp, udp) (default: https)
--https-upgrade	Upgrade HTTP protocol to HTTPS automatically
--device-id <id>	Serving device ID
--gateway-ids <ids>	Comma-separated gateway device IDs (omit to use Edgible managed gateway)
--hostnames <hostnames>	Comma-separated additional hostnames to route to this app
--auth-modes <modes>	Auth modes: none, org, api-key (comma-separated for multiple)
--allowed-orgs <ids>	Comma-separated organization IDs allowed (when org auth is used)
--non-interactive	Run in non-interactive mode
--no-wait	Return after registration without waiting for on-device convergence
--wait-timeout <seconds>	Max seconds to wait for convergence (default: 600)

Examples

edgible application create existing --name myapp --port 3000 --device-id <serving-device>
edgible application create existing --name myapp --port 8080 --device-id <serving-device> --gateway-ids <gw1,gw2>
edgible application create existing --name myapp --port 3000 --auth-modes org,api-key --device-id <serving-device>
edgible application create existing --non-interactive --name myapp --port 3000 --device-id <serving-device>

edgible application create docker-compose

Create application from docker-compose file (on device)

edgible application create docker-compose [flags]

Flag	Description
-n, --name <name>	Application name
-d, --description <description>	Application description
--compose-file <file>	Path to docker-compose.yml file
--device-id <id>	Serving device ID
--gateway-ids <ids>	Comma-separated gateway device IDs (omit to use Edgible managed gateway)
--hostnames <hostnames>	Comma-separated additional hostnames to route to this app
--auth-modes <modes>	Auth modes: none, org, api-key (comma-separated for multiple)
--allowed-orgs <ids>	Comma-separated organization IDs allowed (when org auth is used)
--non-interactive	Run in non-interactive mode
--no-wait	Return after registration without waiting for on-device convergence
--wait-timeout <seconds>	Max seconds to wait for convergence (default: 600)

Examples

edgible application create docker-compose --name myapp --compose-file ./docker-compose.yml
edgible application create docker-compose --name myapp --auth-modes org --device-id <serving-device>
edgible application create docker-compose --non-interactive --name myapp --compose-file ./docker-compose.yml --device-id <serving-device>

edgible application create managed-process

Create application from a managed process (agent runs the command)

edgible application create managed-process [flags]

Flag	Description
-n, --name <name>	Application name
-d, --description <description>	Application description
-c, --command <command>	Command to execute
-p, --port <port>	Port number the process will listen on
--working-dir <dir>	Working directory for the process
--env <vars>	Environment variables (format: KEY=VALUE,KEY2=VALUE2)
--log-file <path>	Path to log file for stdout/stderr
--protocol <protocol>	Protocol (http, https, tcp, udp) (default: https)
--device-id <id>	Serving device ID
--gateway-ids <ids>	Comma-separated gateway device IDs (omit to use Edgible managed gateway)
--hostnames <hostnames>	Comma-separated additional hostnames
--auth-modes <modes>	Auth modes: none, org, api-key (comma-separated for multiple)
--allowed-orgs <ids>	Comma-separated organization IDs allowed (when org auth is used)
--non-interactive	Run in non-interactive mode
--no-wait	Return after registration without waiting for on-device convergence
--wait-timeout <seconds>	Max seconds to wait for convergence (default: 600)

Examples

edgible application create managed-process --name myapp --command "node server.js" --port 3000
edgible application create managed-process --name myapp --command "python app.py" --port 8080 --working-dir /opt/myapp
edgible application create managed-process --name myapp --command "npm start" --port 3000 --auth-modes api-key
edgible application create managed-process --non-interactive --name myapp --command "npm start" --port 3000 --device-id <serving-device>

edgible application create vm

Create a VM application (managed by the agent via QEMU or other backends)

edgible application create vm [flags]

Flag	Description
-n, --name <name>	Application name
-d, --description <description>	Application description
--backend <backend>	VM backend (qemu) (default: qemu)
--disk-image <path>	Disk image path or URL
--memory <mib>	Memory in MiB (default: 512)
--cpus <count>	Number of CPUs (default: 1)
--ssh-port <port>	Host port forwarded to VM port 22 (default: 2222)
--ssh-public-key <key>	SSH public key to inject via cloud-init
--arch <arch>	VM architecture: x86_64 or aarch64 (default: x86_64)
--device-id <id>	Serving device ID
--gateway-ids <ids>	Comma-separated gateway device IDs
--hostnames <hostnames>	Comma-separated additional hostnames
--auth-modes <modes>	Auth modes: none, org, api-key
--allowed-orgs <ids>	Comma-separated allowed organization IDs
--non-interactive	Run in non-interactive mode
--no-wait	Return after registration without waiting for on-device convergence
--wait-timeout <seconds>	Max seconds to wait for convergence (default: 600)

Examples

edgible application create vm --name my-vm --backend qemu --disk-image /var/lib/vms/ubuntu.qcow2 --device-id <id>
edgible application create vm --non-interactive --name my-vm --backend qemu --disk-image /path/to/disk.qcow2 --memory 1024 --cpus 2 --ssh-port 2222 --device-id <id>

edgible application get

Aliases: status, info

Get status of a specific application

edgible application get [app] [flags]

Flag	Description
--app <app>	Application id or name

Examples

edgible application get web                 # by name
edgible application get --app <app-id>
edgible application get web --json | jq '.deploymentIssues'

Notes

--app takes an application id or its name; the bare positional means the same.

edgible application export

Print an application’s canonical declaration as YAML (edit it, then “edgible stack deploy”)

edgible application export [app] [flags]

Flag	Description
--app <app>	Application id or name
--version <n>	Declaration version to export (default: the current one)
--out-file <path>	Write to a file instead of stdout
--redacted	Blank every workload env value (safe to share, NOT re-appliable)

Examples

edgible application export web
edgible application export --app <app-id> --out-file ./edgible.yml
edgible application export web --version 3
edgible application export web --redacted

Notes

By default every workload environment value is included in full. The document can be re-applied with edgible stack deploy, and is sensitive: do not commit it. --redacted blanks every environment value, giving a copy that is safe to share but cannot be re-applied.

edgible application events

Show lifecycle events for an application

edgible application events [app] [flags]

Flag	Description
--app <app>	Application id or name
-n, --limit <number>	Maximum number of events to show (default: 50)
--type <type>	Only show events of this type (eventType or the printed action)
--all	Include no-op state reports (state unchanged) that are hidden by default

Events that report no change of state are hidden by default, because they are periodic reports rather than things that happened. --limit counts the events you can read, so -n 5 returns five real events even when the application reports every minute. --all shows the hidden ones.

--json is never filtered.

Examples

edgible application events web -n 5
edgible application events --app <app-id> --type application_started
edgible application events web --all

edgible application logs

Show live workload logs collected from the application’s serving device(s)

edgible application logs [app] [flags]

Flag	Description
--app <app>	Application id or name
--since <time>	Only lines at/after this time (ISO-8601 or epoch-ms)
-n, --limit <number>	Maximum number of lines per device
--device <id>	Restrict to a single serving device the app is deployed on
--priority <level>	Minimum journald priority: debug, info, warning, err (default: info)
-f, --follow	Poll continuously and stream new lines (Ctrl+C to stop)

Examples

edgible application logs web
edgible application logs web --since 2026-07-06T12:00:00Z --limit 100
edgible application logs web --follow
edgible application logs --app <app-id> --device <serving-device-id> --json
edgible application logs web --follow 2>/dev/null   # only the workload's own lines

Logs are collected on demand from the workload’s own sources (info+ priority by default) over the diagnostics channel; use application events for the historical lifecycle stream.

edgible application trace

Trace the data path for an application hop-by-hop (gateway HAProxy → WireGuard → serving Caddy → workload)

edgible application trace [app] [flags]

Flag	Description
--app <app>	Application id or name
--timeout <ms>	Overall trace timeout budget in milliseconds (server-capped under the API Gateway ceiling)

Examples

edgible application trace web
edgible application trace --app <app-id> --timeout 15000
edgible application trace web --json

Exit code is non-zero when any hop’s verdict is fail (offline devices are reported unknown, not a failure).

edgible application doctor

Diagnose one application: deployment, certificates, data path and workload logs

edgible application doctor [app] [flags]

Flag	Description
--app <app>	Application id or name
--timeout <ms>	Data-path trace timeout budget in milliseconds (server-capped under the API Gateway ceiling)

Examples

edgible application doctor web
edgible application doctor --app <app-id> --timeout 15000
edgible application doctor web --json | jq '.verdict'
edgible application doctor web > evidence.txt

The exit code is non-zero when any layer is faulty. An offline device or unreachable diagnostics is inconclusive, not a failure.

edgible application traffic

Show request telemetry observed on the serving devices (ADR-0026)

edgible application traffic [app] [flags]

Flag	Description
--app <app>	Application id or name
--since <duration>	Window ending now, e.g. 15m, 6h, 7d (default: 24h)
--granularity <unit>	minute (windows up to 6h) or hour
--access <name>	Only this access (primary, or an access name)
--route <path>	Only this route path, e.g. /api/*

Examples

edgible application traffic web
edgible application traffic web --since 1h
edgible application traffic web --since 7d --json | jq '.totals'

Counts are sums over the window; as of is the newest delivered minute. Delivery lags real time by up to 15 minutes.

Every number is a sum over the window, never an average: requests by status class, latency percentiles for the whole request and for the workload’s own answer, bytes in and out, the busiest paths, client addresses, user agents, status codes and TLS versions, sign-in outcomes, and the upstream errors behind unreachable workloads. The percentiles are derived at read time from a fixed log-scale histogram, so they carry bucket-edge resolution rather than being exact order statistics.

Two caveats change how the numbers read. Delivery lags real time by up to fifteen minutes, and client addresses are real only once the gateway forwards them with the PROXY protocol — until then those requests are counted but held out of the client tables. --granularity minute serves windows up to 6 hours and hour up to 31 days; leave it off and the window picks one. Watching your traffic covers all of this, along with the per-minute caps and the organization’s retention and privacy settings.

edgible application requests

List recent request records: every error plus a sample of the rest (ADR-0026)

edgible application requests [app] [flags]

Flag	Description
--app <app>	Application id or name
--since <duration>	Window ending now, at most 6h (default: 1h)
--status <filter>	Status class (5xx), code (404) or range (400-499)
--path <prefix>	Only paths starting with this prefix
--client-ip <ip>	Only this client address
--access <name>	Only this access
-n, --limit <number>	Maximum number of records to return (default: 50)
--cursor <cursor>	Continue from a previous page

Examples

edgible application requests web --status 5xx
edgible application requests web --since 6h --path /api --json

Every 4xx/5xx and upstream error is recorded; other requests are sampled.

Records come back newest first, and the list is evidence rather than a complete log: every 4xx, 5xx and upstream error is kept, while successful requests are sampled (one in fifty by default). Use application traffic when you need counts.

The DETAIL column shows the upstream error when there is one; failing that, the identity that signed in; failing that, the word sample for a sampled success. --limit pages the window, and the command prints the --cursor token to continue with whenever more records remain. Watching your traffic covers the sample rate, the per-minute record cap and how long records are kept.

edgible application access

Show gateway access rules and recent denials for an application

edgible application access [app] [flags]

Flag	Description
--app <app>	Application id or name
-n, --limit <number>	Maximum number of recent denials to return (default: 50)

Examples

edgible application access web
edgible application access --app <app-id> -n 200
edgible application access web --json | jq '.decisions[] | select(.decision == "deny-ip")'

Deny beats allow. An empty allow list means all sources; edit either list with edgible application update.

edgible application update

Update an existing application (e.g. auth modes, name)

edgible application update [app] [flags]

Flag	Description
--app <app>	Application id or name
-n, --name <name>	Application name
--auth-modes <modes>	Auth modes: none, org, api-key (comma-separated for multiple)
--allowed-orgs <ids>	Comma-separated organization IDs allowed (when org auth is used)
--target-state <state>	Target lifecycle state: running, suspended

Examples

edgible application update web --name web-prod
edgible application update web --auth-modes org,api-key
edgible application update web --auth-modes org --allowed-orgs org-a,org-b
edgible application update web --target-state suspended    # stop serving, keep the record

Notes

--name RENAMES the application. To point the verb at an application by name, use --app <name> (or the bare positional).

edgible application delete

Aliases: rm

Delete an application

edgible application delete [app] [flags]

Flag	Description
--app <app>	Application id or name
-y, --yes	Skip the confirmation prompt
--no-wait	Return as soon as the platform accepts the delete, without waiting for per-device teardown
--wait-timeout <seconds>	Max seconds to wait for teardown (default: 120)

Examples

edgible application delete web
edgible application delete --app <app-id> --yes
edgible application delete web --yes --wait-timeout 300
edgible application delete web --no-wait           # CI: fire and forget
edgible application delete web --non-interactive   # CI: never prompt, for anything

Notes

--non-interactive means never prompt, confirmation included — it does not need --yes as well. The command waits for per-device teardown by default (as every application create verb waits for convergence); --no-wait returns as soon as the platform has accepted the delete and lets the devices tear down afterwards.

edgible application releases

List the cut releases for an application (version, status, current pointer, signature)

edgible application releases [app] [flags]

Flag	Description
--app <app>	Application id or name

Examples

edgible application releases web
edgible application releases web --json | jq '.releases[] | select(.isCurrent)'

A release is cut when a declaration is applied (edgible stack deploy, or any application create verb). Roll back to one with edgible application rollback.

edgible application rollback

Re-point the deployment at an earlier cut release (no new version, no tag re-resolve)

edgible application rollback <version> [flags]

Flag	Description
--app <app>	Application id or name
-y, --yes	Skip the confirmation prompt

Examples

edgible application rollback 3 --app web
edgible application rollback 3 --app web --yes      # CI: no confirmation

Notes

<version> is a release version from edgible application releases, not a declaration version. The rollback re-points the deployment at the exact digest-pinned bytes that release was cut with: no new version is cut and no image tag is re-resolved. The application takes --app here rather than a positional, because the positional is the version.

edgible application redeploy

Force re-realization of the current release on its device(s) (no version cut)

edgible application redeploy [app] [flags]

Flag	Description
--app <app>	Application id or name

Examples

edgible application redeploy web

Notes

Nudges the serving agent to force-recreate the workload from the CURRENT release. Nothing changes: no version is cut and the deployment pointer is untouched. Use it when the device and the control plane agree but the workload itself is wedged.

edgible application rollout

Inspect release rollout across an application’s devices

edgible application rollout [flags]

edgible application rollout status

Show which devices have converged on the current release

edgible application rollout status [app] [flags]

Flag	Description
--app <app>	Application id or name

Examples

edgible application rollout status web
until edgible application rollout status web; do sleep 5; done   # CI gate
edgible application rollout status web --json | jq '.summary'

The exit code is the contract: 0 when every device is on the current release, 1 while any device is still pending. It applies in both table and --json modes.

edgible application api-keys

Aliases: keys

Manage application API keys

edgible application api-keys [flags]

edgible application api-keys list

Aliases: ls

List API keys for an application

edgible application api-keys list [flags]

Flag	Description
--app <app>	Application id or name

Examples

edgible application api-keys list --app web
edgible application api-keys list --app web --json | jq '.keys[].keyPrefix'

edgible application api-keys create

Aliases: new

Create a new API key

edgible application api-keys create [flags]

Flag	Description
--app <app>	Application id or name
-n, --name <name>	Key name
--expires <date>	Expiration date (ISO format)

Examples

edgible application api-keys create --app web --name ci-runner
edgible application api-keys create --app web --name temp --expires 2026-12-31

Notes

The key is shown once and never again. Save it before closing this terminal.

edgible application api-keys delete

Aliases: rm

Delete an API key

edgible application api-keys delete [flags]

Flag	Description
--app <app>	Application id or name
-y, --yes	Skip the confirmation prompt
-k, --key-id <id>	API Key ID

Examples

edgible application api-keys delete --app web            # pick the key interactively
edgible application api-keys delete --app web --key-id <key-id> --yes

edgible application short-codes

Aliases: codes

Manage application short codes

edgible application short-codes [flags]

edgible application short-codes list

Aliases: ls

List short codes for an application

edgible application short-codes list [flags]

Flag	Description
--app <app>	Application id or name

Examples

edgible application short-codes list --app web
edgible application short-codes list --app web --json

edgible application short-codes create

Aliases: new

Create a new short code

edgible application short-codes create [flags]

Flag	Description
--app <app>	Application id or name
-n, --name <name>	Code name/description
--expires <date>	Expiration date (ISO format)
--max-uses <number>	Maximum number of uses

Examples

edgible application short-codes create --app web --name "demo for acme"
edgible application short-codes create --app web --name onboarding --max-uses 1
edgible application short-codes create --app web --name trial --expires 2026-12-31

A short code is a shareable 6-character token that grants a session into the application without an Edgible account.

edgible application short-codes delete

Aliases: rm

Delete a short code

edgible application short-codes delete [flags]

Flag	Description
--app <app>	Application id or name
-y, --yes	Skip the confirmation prompt
-c, --code-id <id>	Short Code ID

Examples

edgible application short-codes delete --app web           # pick it interactively
edgible application short-codes delete --app web --code-id <code-id> --yes

edgible application short-codes toggle

Enable or disable a short code

edgible application short-codes toggle [flags]

Flag	Description
--app <app>	Application id or name
-c, --code-id <id>	Short Code ID

Examples

edgible application short-codes toggle --app web --code-id <code-id>

Toggling is a flip, not a set: a disabled code is enabled and vice versa. Read the current state with edgible application short-codes list.

edgible application storage

Manage application storage records (platform + host-bind)

edgible application storage [flags]

edgible application storage list

Aliases: ls

List storage records (platform + host-bind) for an application

edgible application storage list [flags]

Flag	Description
--app <app>	Application id or name

Examples

edgible application storage list --app web
edgible application storage list --app web --json

Records are what the agent OBSERVED on the device, which is not necessarily what the declaration says: an undeclared host-bind volume shows here first and is proposed for declaration by edgible application storage declare.

edgible application storage declare

Propose spec.storage[] entries for undeclared host-bind volumes

edgible application storage declare [flags]

Flag	Description
--app <app>	Application id or name
-y, --yes	Accept all proposals without prompting (CI-friendly)
--non-interactive	Skip prompts even on a TTY (use with —yes)

Examples

edgible application storage declare --app web
edgible application storage declare --app web --yes --non-interactive   # CI
edgible application storage declare --app web --json | jq '.proposals'

The command prints a YAML snippet to paste into spec.storage[]. It does not change the declaration itself.

edgible application storage promote

Promote a host-bind storage record to platform-managed storage on its serving device

edgible application storage promote [flags]

Flag	Description
--app <app>	Application id or name
-s, --storage-name <name>	Storage record name
--mobility <mobility>	Final mobility for the promoted record: immovable | movable | replicated (default: immovable)
--watch	Wait for the promote job to complete and report status

Examples

edgible application storage promote --app web --storage-name data
edgible application storage promote --app web --storage-name data --watch
edgible application storage promote --app web --storage-name data --mobility movable

Promotion copies the data into platform-managed storage on the same device; --mobility movable is what makes the volume eligible for placement elsewhere later.

edgible application storage push

Ship local data into a storage volume on the application’s device

edgible application storage push [flags]

Flag	Description
--app <app>	Application id or name
-s, --storage-name <name>	Storage entry name (must exist in the application declaration)
-p, --path <path>	Local file or directory to push
--device-id <id>	Target device (defaults to the application’s first device)
--no-pack	Treat —path as a pre-built tarball; do not pack with tar
--quiesce	Stop the workload across the apply step (recommended for stateful apps)
--apply-mode <mode>	Apply mode: replace | merge (default: replace)

Examples

edgible application storage push --app web --storage-name data --path ./seed
edgible application storage push --app web --storage-name data --path ./seed --quiesce
edgible application storage push --app web --storage-name data --path ./dump.tar --no-pack
edgible application storage push --app web --storage-name data --path ./seed --apply-mode merge

--quiesce stops the workload across the apply step, which is what a stateful application (a database, anything with an open write handle) needs. replace wipes the volume first; merge overlays the pushed tree onto it.

edgible application ssh

Open an SSH session to a VM application

edgible application ssh [app] [flags]

Flag	Description
--app <app>	Application id or name
-u, --user <username>	SSH username (default: ubuntu)
-k, --key <path>	Path to SSH private key
--command <cmd>	Run a single command instead of interactive session

Examples

edgible application ssh my-vm
edgible application ssh --app <app-id> --user root --key ~/.ssh/id_ed25519
edgible application ssh my-vm --command "uname -a"

Notes

Only VM applications support this. With no --key, the VM’s private key is fetched into a temporary file that only you can read, then deleted.