Native CLI

Sign in from a terminal, call the twelve tools, move verified files and run hosted productions with the wavemaker CLI. The CLI has no public release yet.

Updated 2026-10-23

The wavemaker command-line tool signs you in to Wavemaker, calls the twelve tools, uploads and downloads verified files, runs hosted productions from a brief, and opens a local agent terminal. It is a single native executable for macOS, Linux and Windows. This page covers availability, sign-in, every command group with its flags, JSON output, exit codes and where the CLI keeps its files.

Availability

Releases are built for six targets:

When a release exists, the installers download the archive and its checksum from the same release, check the digest, target, version and publisher signature, and only then replace the binary. They install for your user only, without administrator rights. Homebrew, Scoop and WinGet commands appear on the Download page once those channels are published.

Once installed, these commands manage the installation:

wavemaker --version
wavemaker self status --json
wavemaker self update

• self status shows the version, target, install channel and, when the release is reachable, the latest published version.
• self update [--version X] replaces a script-installed binary after the same digest and publisher checks. It refuses while a local session supervisor from this configuration is running.
• A Homebrew, Scoop or WinGet install is updated by its manager: self update exits with code 2 and prints the manager's upgrade command.
• Interactive chat offers Update now, Skip or Skip until next version when a newer release is published. Pass --no-update-check or set WAVEMAKER_NO_UPDATE_CHECK=1 to skip that check.

Sign in

1. Select the production service once: wavemaker service select https://api.wavemaker.io.
2. Run wavemaker login. Your browser opens Wavemaker's sign-in and consent page.
3. Approve the requested permissions. The terminal reports that it is connected.
4. Run wavemaker auth status --json to confirm the saved credential.

wavemaker service select https://api.wavemaker.io
wavemaker login
wavemaker auth status --json
# → {"schema":"wmlab.result/1","ok":true,"data":{"service":"https://api.wavemaker.io",
#    "credential_source":"local_file","state":"locally_unexpired","expires_at":1793000000.0,
#    "environment_token_present":false,"scopes":["read","run","write","agent"]},"error":null}

• Sign-in uses OAuth with PKCE and a callback on 127.0.0.1. If no browser opens, the CLI prints the sign-in link; open it on the same computer.
• The browser step must finish within 180 seconds, or the command fails with "Sign-in timed out".
• login requests read run write agent. login --publish also requests publish.
• Normal commands renew an expired access token on their own and replay the rejected request once. If renewal is refused, the command fails with login_required: run wavemaker login again in your own terminal. An agent can't complete that browser step for you.

Credential states

auth status reads the saved credential without contacting the service, so a locally valid credential is not proof the service still accepts it.

wavemaker auth logout removes the selected service's saved credential. It does not revoke the grant on the server; revoke it in Connections › App grants.

Use a developer credential instead

For CI and other non-interactive use, set WAVEMAKER_TOKEN to a developer credential from Connections › Developer setup. It overrides the saved sign-in and is never renewed: when it expires, commands fail until you replace it. See Client credentials and provider keys.

export WAVEMAKER_SERVICE=https://api.wavemaker.io
export WAVEMAKER_TOKEN="$(cat /path/to/private/credential)"
wavemaker api call read --arguments '{"uri":"wm://credits"}' --json

Global options

These work with every command:

A service origin must be HTTPS, or plain HTTP on your own machine (127.0.0.1, localhost or [::1]). Running wavemaker with no command opens the chat terminal.

Commands

Account and setup

doctor never signs in, refreshes a credential or starts a model turn. doctor --probe reports the saved credential's local state separately from what the service says about it.

Tools and operations

api call options:

A tool name sends POST /v1/tools/{tool}. Any other name must be an older operation the CLI knows; an unknown name is refused before anything is sent. --request-id and --remote-project apply only to tools; operations take those values inside their own arguments.

Models

wavemaker models searches the service catalog for models Wavemaker runs and provider routes.

--offset, --include-mature and --source self-hosted apply only to a direct Comfy connection; against the service they are refused with argument_invalid, and you page with --cursor instead. A listed model doesn't prove you have credits or provider access for it.

Hosted productions

make asks the hosted Wavemaker agent to produce something from a brief. It creates a session, posts the brief as its first turn, and follows the run until it ends or asks for an approval.

The run id is the session id. Manage a run with production:

steer, approve and interrupt take over the run's controller lease first, so they work from any terminal signed in to the same workspace.

Jobs and files

files download takes KIND artifact, input, package, project or model (a model also needs --version). Other flags: --file, --revision, --chunked, --timeout (default 600 seconds), and --resume or --discard with --workspace-scope for resumable transfers. Downloads refuse an existing destination. File transfers allow 600 seconds each by default.

When a resumable upload fails after the service acknowledged part of it, keep the error.details.resume object from the reply privately and pass it back with --resume-file.

Projects, inputs and artifacts

Graphs and Comfy

Without a direct Comfy connection, these commands use the selected Wavemaker service. With one, run and models work against your own Comfy and need no Wavemaker sign-in. See Graph portability.

Local agent terminal

chat options include --agent codex|grok|claude (default codex), --model, --native to open the agent's own interface, --print-command to show what would run, --shared-workspace to edit the project directory in place, --import FILE, --no-splash and --permission-mode oneshot|accept-edits|plan|auto.

chat --agent picks a program installed on your computer, signed in with its own provider account; that is separate from your Wavemaker account and from make --agent, which picks the hosted agent. wavemaker doctor lists the agents it finds. Chat needs an interactive terminal; use session commands for automation.

Other commands

runs lists a direct Comfy connection's runs. media, provider voices, assets voice, agent-models, tools and exec cover local media rendering, voice catalogs, saved voices, self-hosted agent model profiles, the command catalog and explicit native programs. Run wavemaker COMMAND --help for each one's flags.

JSON output

With --json, every command prints one line of JSON on stdout:

{"schema": "wmlab.result/1", "ok": true, "data": {}, "error": null}

• On success, data holds the result. A tool call's data is the service's {data, job, cost, hints}, so a job id is at data.job.id.
• On failure, ok is false and error is {code, message, details}. Branch on error.code.
• Invalid arguments with --json also produce an envelope, with code argument_invalid.
• Without --json, results are formatted for reading and errors go to stderr.
• --json can't wrap the chat terminal, exec or completions; use chat --print-command --json to inspect chat.

Exit codes

chat exits with the agent program's own exit code.

Common error codes

Service errors such as insufficient_credits, scope_denied or rate_limited pass through with their own codes. See Errors and retries.

Configuration files

• settings.json holds the service saved with service select or login.
• One credential file per service origin, kept outside your projects. The directory is private to your user.
• update-check.json caches the latest published version for a day.
• Use --config-dir or WAVEMAKER_CONFIG_DIR to keep a separate set, for example per CI job.

The service is chosen in this order: --service, then WAVEMAKER_SERVICE, then the saved selection, then the build's default. Never put credentials in graphs, command arguments, source control or shared logs.

Worked examples

Search the catalog and read a route's request schema:

wavemaker api call search --arguments '{"query":"vertical video ad","kinds":["card","format"],"limit":5}' --json
wavemaker models --query kling --json
wavemaker api call read --arguments '{"uri":"wm://route/kling.video"}' --json

Price a call, run it, then collect the result:

wavemaker api call generate --file still.json --json            # still.json sets "quote_only": true
wavemaker api call generate --file still-run.json --request-id hero-still-v1 --json
# → {"schema":"wmlab.result/1","ok":true,"data":{"data":{...},"job":{"id":"9b1e...","state":"queued"},"cost":{...},"hints":[]},"error":null}
wavemaker watch 9b1e... --timeout 600
wavemaker outputs 9b1e... --out ./outputs

If the observation times out, repeat the api call with the same --request-id. The service returns the original job and never runs it twice.

Have the hosted agent make an ad:

wavemaker make "A 15-second vertical video ad for a coffee shop" --quote-only --json
wavemaker files upload logo.png --json
wavemaker make "A 15-second vertical video ad for a coffee shop" \
  --deliverables deliverables.json --attach SHA256 --request-id coffee-ad-1
wavemaker production steer RUN_ID "Make the end card brighter."

Cancel a job explicitly:

wavemaker api call write --arguments '{"uri":"wm://job/JOB_ID","cancel":true}' --json

Related

• Connect to Wavemaker
• Client credentials and provider keys
• Quote and run work
• Graph portability

Related guidance

• Quote and run work
• Errors, limits and safe retries
• Graph portability and explicit dependencies
• Client credentials and provider keys
• Connect an external agent with MCP
• Connect to Wavemaker