Guide

The dak CLI

DAK (Dezifi Agent Kit) declares agents, tools, policies, guardrails, knowledge bases, widgets and evals as code. dak turns that code into templates and deploys them to a workspace.

Install and authenticate

terminal

npm install -g @dezifi/cli@0.1.0-beta.3     # installs the dak command
# or per project: npm install --save-dev @dezifi/cli@0.1.0-beta.3  (then run it as npx dak)

export DEZIFI_SECRET_KEY=sk_dezifi_...       # a deploy key (see below); never commit it
export DEZIFI_WORKSPACE_ID=<workspace id>    # optional: skips the slug lookup in dak.json
dak doctor                                   # checks Node, dak.json, the key and ~/.dezifi

The deploy key is a service account key (Settings > Service Accounts, then a key for it in API Keys). Give it only to the CLI and CI.

dak.json

dak init <appName> writes one with dev and prod environments. synth.app is the command that runs your program; it is started without a shell, so pipes and $VARS are not expanded.

dak.json

{
  "app": "docs-qa",
  "outdir": "dak.out",
  "defaultEnvironment": "dev",
  "environments": {
    "dev": { "workspace": "<your-workspace-slug>", "apiBaseUrl": "https://api.dezifi.ai" }
  },
  "synth": { "app": "tsx src/app.ts" }
}

Everyday commands

terminal

dak synth                       # run your app, write dak.out/
dak diff                        # ask the platform to validate the templates; changes nothing
dak deploy                      # synth, resolve secrets on this machine, deploy, wait for the result
dak deploy --json > deploy.json # machine-readable: stack id, resources with physical ids, one-time outputs
dak status <StackName>          # the platform's current status (use it after a timeout)
dak deploy --enforce-gates      # also re-run the stack's eval gates; a breach fails the deploy (exit 23)
dak destroy <StackName>         # tear the stack down

--env <name> (or -e) picks an environment from dak.json. dak <command> --help prints that command's usage and never runs it; an option a command does not know is refused (exit 2) rather than ignored.

Waiting for a deploy: --timeout and dak status

dak deploy waits until the platform finishes, up to --timeout <seconds> (default 1800). A deploy with a quality bar runs the agent once per test case, so it can take minutes. If time runs out the CLI exits 25: the deploy may still finish on the platform. Run dak status <StackName>; it exits 0 when done, 21 when failed and 25 while still in progress, so a CI job can loop on it.

One-time outputs (minted keys)

A stack that creates an ApiKey prints its secret once, as output <Resource>.apiKey = … (or under outputs with --json). If the deploy finished after its first response, the CLI collects the outputs from the platform, which holds them for 10 minutes, in memory only, for the key that deployed. After that, or after a platform restart, they are gone: rotate the key.

Exit codes

Code	Meaning
0	Success
2	Usage error: unknown command, unknown option or a missing value
10	Configuration missing: no dak.json, no manifest, or a bad DEZIFI_WORKSPACE_ID
11	Authentication failed (DEZIFI_SECRET_KEY missing or refused)
20	Synth failed
21	Deploy failed (the message says which resource and why)
23	An eval gate or quality bar was not met
24	An eval command failed
25	Still deploying when --timeout ran out; it may yet succeed (check dak status)
30	Network error or timeout talking to the platform
99	Unexpected error

Other commands

dak ls: the stacks in dak.out with workspace and resource count.
dak watch: re-synth and deploy on every change under ./src.
dak rag ingest <datasetId> <file> / dak rag status <jobId>: load documents into a knowledge base.
dak eval …: run, gate, compare and optimize experiments; dak eval --help lists them.
dak catalog refresh: regenerate the typed integration and model classes from the platform catalog.