CLI

Run EdgeSpeak workflows from your terminal.

Install

The CLI includes its own local speech runtime, so the desktop app does not need to be installed or running. Choose the command for your operating system.

macOS / Linux

Run this in Terminal. Supports macOS (Apple Silicon) and Linux (x86_64). On Linux, the installer selects the CUDA build if an NVIDIA driver or CUDA environment is detected; otherwise it installs the CPU build. It also downloads the CUDA 12 runtime libraries if they are not already installed. The CUDA build needs NVIDIA driver 570 or newer on RTX 20 series and newer GPUs, and 575 or newer on GTX 900/10 series, P100 and V100; on those GPUs the installer installs the CPU build instead if the driver is older than 575.

curl -fsSL https://edgespeak.com/install.sh | sh

To specify the build manually, pass --device with the same values as edgespeak-cli serve --device:

curl -fsSL https://edgespeak.com/install.sh | sh -s -- --device cuda

Supported --device values (case-insensitive):

sh ~/Downloads/install.sh

Windows

Run this in PowerShell on Windows x64. The installer uses the CPU build by default and adds edgespeak-cli to your user PATH without requiring administrator access.

irm https://edgespeak.com/install.ps1 | iex

The CUDA build needs NVIDIA driver 570 or newer on RTX 20 series and newer GPUs, and 575 or newer on GTX 900/10 series, P100 and V100. To enable CUDA on a supported NVIDIA GPU, explicitly select the CUDA build in the same PowerShell window before installing:

$env:EDGESPEAK_WINDOWS_ACCELERATOR = "cuda"
irm https://edgespeak.com/install.ps1 | iex

You can run edgespeak-cli login as soon as installation finishes. If another open terminal cannot find the command, reopen it so the PATH update takes effect.

Activate

Run edgespeak-cli login to sign in through your browser: new accounts start a 7-day trial and purchased accounts activate this device. For an instant device-bound trial with no browser or account, run edgespeak-cli trial. If you already have a License Key, run edgespeak-cli activate "<LICENSE_KEY>"; pass --stdin to keep the key out of shell history.

edgespeak-cli login

edgespeak-cli trial            # instant device trial, no account or browser
edgespeak-cli activate "<LICENSE_KEY>"
edgespeak-cli activate --stdin   # paste the key, then Ctrl-D

Purchase, account sign-in, and device activation

Guest purchases are linked to an email address: after payment, the License Key belongs to the email entered at Stripe checkout. Signing in with that same email should show the existing lifetime license. A purchase does not create an account password.

Passwords are optional. After signing in with a Key or email link, you can set one in account security settings. Setting a password for the first time only requires a new password and confirmation; changing an existing password requires verifying the current password.

If you paid but only see a trial after signing in, confirm that your sign-in email matches your checkout email, or sign in directly with the purchased License Key on the account page. Signing in with a Key opens the associated account; it does not merge accounts under different emails. edgespeak-cli trial requests an anonymous device trial and does not look up purchases by email. Use login or activate for an existing purchase.

Gift/invite codes can activate devices but cannot sign in to the website. If an invite code is unavailable, you can purchase a License Key and activate it, or contact the person who gave you the invite code for help. A License Key (for software activation) and the API Key used for HTTP authentication below (for interface authentication) are two distinct credentials.

Activation troubleshooting and container startup

edgespeak-cli activate supports reading the key from the EDGESPEAK_LICENSE_KEY environment variable or entering it via --stdin, without requiring a website password. HTTP 404 activation_code_unavailable indicates that the server rejected the gift code; network:dns, network:tls, network:tls_handshake, network:proxy, network:connect, and network:timeout are network failures and do not mean the Key is invalid.

The runtime sets a 30-second timeout per interactive activation attempt, with up to two retries on network failures after 700 ms and 1800 ms respectively. Explicit certificate verification failures (network:tls) and HTTP business rejections are not retried automatically, while interrupted TLS handshakes (network:tls_handshake) are still retried. Retries take up to about 93 seconds, and the CLI displays retry progress in real time. Background refresh uses a 5-second timeout. If activation fails due to network issues, keep the original Key and troubleshoot connectivity; there is no need to purchase another key.

The CLI localizes activation errors and progress prompts in English, Simplified Chinese, Traditional Chinese, German, French, Japanese, and Korean. It uses the first nonempty value in this priority order: EDGESPEAK_CLI_LOCALE → LC_ALL → LC_MESSAGES → LANG. System formats such as zh_CN.UTF-8 are supported; C, POSIX, unsupported languages, and unset values fall back to English. Set the language explicitly in a container:

EDGESPEAK_CLI_LOCALE=zh-CN edgespeak-cli activate
EDGESPEAK_CLI_LOCALE=en edgespeak-cli activate

These commands read the Key from an already configured EDGESPEAK_LICENSE_KEY. The setting affects activation errors and progress only: error codes, exit codes, --json data, and the audio --language option stay unchanged. Other CLI messages remain primarily English. Unknown runtime errors retain their original diagnostics without a purchase recommendation.

Run these credential-free probes inside the failing container:

getent ahosts api.edgespeak.com
curl -sS --connect-timeout 10 --max-time 30 -o /dev/null \
  -w 'http=%{http_code} dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} total=%{time_total}\n' \
  https://api.edgespeak.com/api/health

A successful health probe only establishes that the current network path is reachable; it does not confirm that the activation request succeeded. When troubleshooting, record the timestamp, CLI version, error category, and probe results. Never share your License Key or credential-bearing proxy settings. Cross-border connectivity from mainland China can affect connections, but a single send-failure log is not enough to attribute the issue to Cloudflare. Check container DNS, system time, proxy settings, and outbound HTTPS connections while keeping TLS certificate verification enabled.

Do not repeatedly run deactivate && activate when starting containers: this revokes local authorization and makes service startup dependent on network activation. After activating on the target device for the first time, persist the EDGESPEAK_DATA_DIR directory and run serve directly on subsequent restarts. The default data directory on Linux is $XDG_DATA_HOME/EdgeSpeak or $HOME/.local/share/EdgeSpeak. Keep device identities stable, and do not share a single activation data volume across different nodes.

Pass the License Key into the runtime via environment variables or secrets; never write it into Dockerfile ENV or container images. Configure a separate EDGESPEAK_API_KEY when serving remote requests. Recommended container entrypoint configuration:

ENTRYPOINT ["edgespeak-cli"]
CMD ["serve", "--host", "0.0.0.0", "--port", "1118", "--allow-remote"]

Workflows

Transcribe with optional speaker labels, align known text, segment text semantically, synthesize speech, manage voices and models, or open the Realtime demo. When the desktop app is not running, most one-shot commands start the bundled local engine; serve instead keeps a Headless service running for repeated API calls.

edgespeak-cli transcribe meeting.m4a -o meeting.json   # word-level timing in JSON
edgespeak-cli transcribe meeting.m4a --diarize -o speakers.json
edgespeak-cli transcribe meeting.m4a -o transcript.srt
edgespeak-cli align meeting.m4a --text-file transcript.txt -o aligned.json
edgespeak-cli segment --file transcript.txt -o sentences.json
edgespeak-cli speech "Read this aloud" -o speech.wav
edgespeak-cli voices list
edgespeak-cli models list
edgespeak-cli status
edgespeak-cli demo
edgespeak-cli update

Pass --language to transcribe, align, speech and voices add with the same codes as the HTTP API, for example --language yue; see Languages. transcribe --language needs a reachable gateway.

Update models

Available from CLI 0.6.0. Earlier CLI releases do not provide models update and do not automatically refresh installed models.

# Inspect installed models without downloading or changing local model files
edgespeak-cli models update --check
edgespeak-cli models update --check --json

# Update all installed models, or one installed model
edgespeak-cli models update
edgespeak-cli models update EdgeSpeak/Lattice-2
edgespeak-cli models update EdgeSpeak/Lattice-2-Flash

# Install a model that is not already present
edgespeak-cli models download EdgeSpeak/Lattice-2

With no IDs, models update checks installed models supported by the CLI. It does not download the entire catalog. Explicit IDs that are not installed are reported as not_installed; use models download to install them. Shared model bundles are processed once. Stop the desktop app, serve, and MCP sessions before updating; --check can run while a gateway is active.

For EdgeSpeak/Lattice-2-Lite, EdgeSpeak/Lattice-2-Flash, and EdgeSpeak/Lattice-2-Pro, updates cover both the installed transcription model (Transcriber.ES) and translation model (Translator.ES) in that tier. A translation-only installation is included. If only one capability is installed, updating does not install the other. Each tier produces one status entry; if either installed capability fails, the tier reports failed. With no IDs, the same rule applies to all three tiers. EdgeSpeak/Lattice-2 separately updates alignment; EdgeSpeak/Lattice-1 updates its alignment, text segmentation, and speaker diarization bundle.

Lattice models are checked against their remote manifests. TTS and language models are checked against the compatible versions in the installed CLI's catalog, so update the CLI first to discover new catalog versions. Language models retain their installed quantization. Local-only models without a published download are reported as unsupported. Changed files in each capability's bundle are downloaded and verified before replacement; a failed download preserves that bundle's installed files. Capabilities update separately, so a later failure does not undo an earlier successful update.

An installed Lattice-2 Preview model is recognized as an upgrade candidate. The compatible client downloads the release acoustic file, reuses a valid tokenizer, and keeps the Preview files available to older clients.

edgespeak-cli update installs the latest standalone runtime, then the installer invokes the new runtime's models update. This also checks models when reinstalling the same compatible runtime version. If a platform still offers an older CLI without this command, the installer reports that model updates were skipped. The app-bundled CLI leaves software updates to the app and updates models only. On Windows, the CLI hands off to a PowerShell window and exits so its executable can be replaced; read that window for the final result. The immediate Windows exit status confirms only that the updater started. Re-running the install command on an activated machine also updates installed models; if that model update fails, the installation still succeeds and the installer tells you to retry edgespeak-cli models update.

--json returns a check flag and a models array with id, status, and optional error. Status values are updated, up_to_date, update_available, not_installed, unsupported, and failed. A successful check returns exit code 0 even when updates are available. Unsupported local-only models are reported and skipped. A failed or explicitly uninstalled target returns 1. On macOS/Linux, runtime update failure returns 1; if the runtime is installed but model updates fail, update returns 3. Stop any running service and retry edgespeak-cli models update; reinstalling the runtime is unnecessary.

API reuse and paragraph segmentation

When connected to a running local or desktop gateway, the CLI calls the same HTTP APIs. transcribe --diarize corresponds to /v1/audio/transcriptions with response_format=diarized_json and runs speaker diarization alongside transcription; diarize corresponds to /v1/speaker/diarizations and returns only a speaker timeline. Given identical inputs, models, and processing configurations, the computation pipeline is identical, though default configurations between desktop and standalone modes may differ.

edgespeak-cli transcribe meeting.m4a --diarize --base-url http://127.0.0.1:1117/v1 -o speakers.json
edgespeak-cli diarize meeting.m4a -o timeline.json
edgespeak-cli segment --file transcript.txt --paragraph-threshold 0.5 -o paragraphs.json
edgespeak-cli segment --transcript aligned.json -o resegmented.json

segment --file reads plain text; --transcript reads transcription or alignment JSON containing segments[].words[], re-segments sentences, and maps word-level timestamps. The --text, --file, and --transcript input options are mutually exclusive.

--paragraph-threshold enables paragraph segmentation and corresponds to the API's paragraph_threshold parameter. Each segments[] element in the returned result represents a paragraph without timestamps; omitting this parameter defaults to sentence segmentation. See the API reference for full parameters and the text normalization endpoint.

Headless API service

Run a persistent HTTP service without the desktop app. The commands below use Bash/zsh (or WSL / Git Bash on Windows); PowerShell environment syntax is shown below.

Start locally and check the service

When EDGESPEAK_API_KEY is unset, starting the service locally requires no authentication by default. This command clears any inherited key on startup to ensure authentication is disabled for this example:

env -u EDGESPEAK_API_KEY edgespeak-cli serve

The service listens on 127.0.0.1:1118 by default and runs in the foreground. Keep that terminal open and send a health check request from another terminal:

export EDGESPEAK_BASE_URL=http://127.0.0.1:1118/v1
curl --fail-with-body "$EDGESPEAK_BASE_URL/health"

Example output:

{"status":"ok","license":"active"}

See Check service health for license values and their meanings. /health and /v1/health never require authentication; HTTP 200 only confirms the service process is reachable. To verify the authentication mechanism, call the protected endpoint below. Before running inference, you must sign in or activate and download and load a model; starting the service successfully does not mean models are ready. Press Ctrl-C to stop the service.

Control authentication from the command line

Non-loopback addresses always require --allow-remote. --allow-unauthenticated-loopback is a legacy loopback-only alias and cannot be used together with --allow-remote. Disabling authentication on non-loopback addresses applies only to isolated test environments.

Enable authentication: stop any running service, set the API Key on the server, and restart it (replace the placeholder in the example):

export EDGESPEAK_API_KEY="your-long-random-secret"
edgespeak-cli serve

In the client terminal, set the same key and call a protected endpoint to verify:

export EDGESPEAK_BASE_URL=http://127.0.0.1:1118/v1
export EDGESPEAK_API_KEY="your-long-random-secret"
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/downloads" \
  -H "Authorization: Bearer $EDGESPEAK_API_KEY"

Example output (no recorded download tasks):

{"object":"list","data":[]}

A missing or incorrect key returns HTTP 401. Request headers also support x-api-key: $EDGESPEAK_API_KEY instead of Bearer format.

Disable authentication: stop the service and restart with the --allow-unauthenticated flag. This flag takes precedence over environment variables:

edgespeak-cli serve --allow-unauthenticated

In PowerShell, enable authentication with the following command. To remove the environment variable, run Remove-Item Env:EDGESPEAK_API_KEY -ErrorAction SilentlyContinue before starting the service. --allow-unauthenticated works the same across all platforms.

$env:EDGESPEAK_API_KEY = "your-long-random-secret"
edgespeak-cli serve

These environment variables are server configuration and do not change with the request-example toggle on API pages. A client subcommand's --api-key option is used only for sending requests; serve configures its key via environment variables and does not support using that client option to set the server key.

Save and rotate a key

serve reads EDGESPEAK_API_KEY once at startup. It never generates, saves, expires or refreshes a key, changing the variable while the service runs has no effect on the running process, and the desktop app's authentication toggle and Regenerate action do not touch it. Use a long random value from your own secret storage. To rotate, stop the service, export the new value, start it again, and update every client; the old key then returns HTTP 401.

export EDGESPEAK_API_KEY="your-long-random-secret"
edgespeak-cli serve

The CLI does not require the sk-edgespeak- prefix. Keys look like the ones the desktop app generates, but the values are independent. See API Key storage and rotation.

Allow access from another machine

Set a key on the server and explicitly enable non-loopback listening:

export EDGESPEAK_API_KEY="your-long-random-secret"
edgespeak-cli serve --host 0.0.0.0 --port 1118 --allow-remote

When sending requests, clients must replace 0.0.0.0 with the server's actual IP address and use the same key. See the full remote-access example.

Model and runtime options

Specify the language model context window at service startup with the --context-tokens option. It defaults to 8192 tokens and applies to local language model workers started by this process. Headless Server does not read context choices saved in the desktop app.

edgespeak-cli serve --context-tokens 32768

For native video requests, frame sampling rates are determined automatically by the model catalog; configuring a video FPS parameter is neither needed nor supported. Context length and sampled video frames share the same memory and token budget. See Native video input and context window for request formats, runtime dependencies, and resource overhead.

Concurrency options

These serve options accept 1..64; 0 does not mean unlimited.

edgespeak-cli serve --speech-concurrency 2 --transcription-concurrency 2

Transcription and transcript alignment are independent capabilities that can execute concurrently instead of sharing a single execution slot, though they still share global upload and native memory budgets. Requests exceeding concurrency limits enter a queue. HTTP speech, transcription, and underlying ASR / TTS queues prioritize reusing loaded models within a fairness bound: the oldest waiting request can be overtaken at most twice, and overtaking is disallowed once it has waited longer than 1 second. This does not guarantee execution begins within 1 second; active tasks and long-lived connections must still finish first.

Concurrency limits do not equal the number of model instances. The same ASR model can be reused by batch jobs and Realtime sessions; switching model variants requires waiting for previous model sessions to be cleaned up. TTS tasks share a single model execution slot. LLMs remain scheduled by the native runtime, currently loading at most one model at a time with a dedicated inference slot. Increasing concurrency parameters does not duplicate models or guarantee throughput gains; memory shortages, unsupported configurations, and native failures will still return errors.

When configuring client timeouts, account for queue wait times, model loading, and actual inference; the same applies to Realtime handshake timeouts. Canceling a queued request immediately removes its registration; if a request has already entered inference execution, model resources are released only after the task finishes or is cleaned up. Inspect waiting and active requests.

Model sleep and residency

By default, the CLI service releases memory or VRAM after 300 seconds (5 minutes) of model inactivity, reloading models on subsequent calls. Active tasks and leased sessions are not forcibly interrupted due to timeouts, and the HTTP service continues listening. --preload only preloads specified models when the service starts.

To change that:

edgespeak-cli serve --preload transcribe --no-model-sleep
# Or choose an idle timeout in seconds:
edgespeak-cli serve --model-idle-seconds 600

--no-model-sleep disables automatic idle unloading. --model-idle-seconds accepts 0..86400 seconds: 0 releases memory as soon as the model becomes idle, while 86400 is a sentinel meaning "never unload due to inactivity" (not a 24-hour timeout). These two options are mutually exclusive and cannot be used together. You can also configure this via the EDGESPEAK_ENGINE_IDLE_TTL_SECS environment variable, though command-line options take precedence; desktop app settings do not sync to the standalone CLI.

This policy covers all models including ASR, LLM, TTS, forced alignment, semantic segmentation, diarization, and speaker embeddings. Disabling sleep still allows switching models on request, explicit unloading, and cleanup on process exit, but it does not bypass hardware resource limits or guarantee that all models remain resident concurrently. To reuse models, keep a serve process running; one-shot CLI commands exit and release models immediately after execution.

Agents

Drive EdgeSpeak from agents via the EdgeSpeak Skill, or integrate the local gateway and MCP into automation and CI environments.

Privacy

Speech workflows and installed local models keep source audio, voices, generated audio, transcripts, prompts, and images on this device. Only when you explicitly select a model reported as execution_location=remote is that request sent to its configured provider.

Generate with a local model

Start the desktop gateway or CLI service and point the EDGESPEAK_BASE_URL environment variable to its address. Download and load a model from the model catalog before calling it:

edgespeak-cli models load Qwen/Qwen3.5-4B
edgespeak-cli generate "Summarize the meeting" --model Qwen/Qwen3.5-4B
edgespeak-cli generate "Describe this image" --image screenshot.png --json