DENGEL / DOCS

Dengel CLI reference

Use the dengel CLI to inspect runs, review proposals, read signed Receipts, or hand off a candidate from a coding session. The standalone CLI is open source under Apache-2.0. Gateway operations require an enabled workspace.

CLI quickstart

Run this in your terminal on macOS or Linux.

curl -fsSL https://dengel.dev/install.sh | sh

The installer verifies the SHA-256 checksum, installs to ~/.local/bin, and opens Dengel in your browser. Sign in if prompted, check that the terminal and browser show the same code, then approve the named workspace. The installer checks the connection before showing a short welcome message.

If your shell cannot find dengel, add the install directory to PATH. Then check the installed version and workspace connection.

export PATH="$HOME/.local/bin:$PATH"
dengel --version
dengel status

The status command lists runs in the approved workspace. A new workspace may have an empty run list. On SSH, use the link printed in the terminal. To install without signing in, run curl -fsSL https://dengel.dev/install.sh | sh -s -- --no-login. This is also the install command for unattended agents that use project credentials.

The CLI connects to the hosted Gateway. To run a Git server locally, use the standalone Dengel Git quickstart.

Manual downloads

Download Dengel CLI 0.5.6 for your operating system and CPU. If you are unsure which to choose, run uname -sm in the terminal or agent runtime where you will install it.

Operating system CPU Download
macOS 11 or later Apple silicon (arm64) macOS Apple silicon
macOS 11 or later Intel (x86_64) macOS Intel
Linux with glibc 2.28 or later ARM64 (aarch64) Linux ARM64
Linux with glibc 2.28 or later x86-64 (x86_64) Linux x86-64

Download the SHA-256 checksums and compare the entry for your archive with shasum -a 256 ARCHIVE on macOS or sha256sum ARCHIVE on Linux before extracting it. The macOS binaries are ad hoc signed and have no Apple notarization.

From the download directory, replace the archive name below with the one you downloaded:

tar -xzf dengel-0.5.6-macos-arm64.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 0755 ./dengel "$HOME/.local/bin/dengel"
export PATH="$HOME/.local/bin:$PATH"
dengel --version

Add the install directory to the shell or agent runtime's PATH. For Git submission, the runtime also needs Git and a configured project credential helper.

To build it yourself, download and verify the standalone source archive. Extract it, open the resulting directory, and run cargo build --locked --release with a current stable Rust toolchain. The executable is target/release/dengel. The source archive includes the lockfile, tests, and Apache-2.0 license. Each binary archive includes license notices.

Authenticate for Gateway commands

Run dengel login to connect an existing installation. Use dengel login --no-browser to print the approval link. The CLI renews its short-lived Gateway token from a private local credential for up to seven days while the approving browser session and workspace membership remain valid. Run dengel logout to revoke the saved login.

Manual token for scripts

Set DENGEL_GATEWAY_TOKEN to use an explicit workspace token in place of the saved login. Sign in to the Dengel panel and select the workspace that owns the resource. In that same signed-in browser, open the CLI token endpoint and copy only the string inside the JSON token field. Paste that string without its quotation marks at the silent Bash prompt:

read -r -s -p 'Dengel CLI token: ' DENGEL_GATEWAY_TOKEN
printf '\n'
export DENGEL_GATEWAY_TOKEN
dengel --json status

If the Gateway returns 401 unauthenticated, check that the pasted text contains only the token value. The "token": label, quotes, or braces from the JSON response will cause a 401. Get a fresh token if it expired or you switched workspaces.

The token acts as your current workspace member and is delegated to the CLI. The default endpoint is https://api.dengel.dev/v1. Set DENGEL_GATEWAY_URL only if your deployment supplies a different Gateway URL. If your workspace uses a separate Cloudflare Access sign-in, the CLI can read its application token from a private file named by DENGEL_CLOUDFLARE_ACCESS_TOKEN_FILE. Ask your early-access contact for the Access setup for that environment. Keep credentials out of command arguments, URLs, logs, and agent prompts. Clear DENGEL_GATEWAY_TOKEN when finished.

Prepare a managed Build

These commands require CLI 0.4.0 or later. Use dengel login to connect the workspace that has access to managed Build and the repository.

For a Linear issue import, dengel build preview --body spec.json and dengel build create --body spec.json require a GitHub repository connected to the workspace and a request-scoped read-only Linear MCP grant in the spec's linear_mcp_token field. The Dengel login authorizes Gateway requests. The panel's Linear connection supplies the separate grant to panel requests. To import an issue with that connection, start the build in the panel.

Use the build ID from the panel and a prepared TOML plan to request a draft quote from the CLI:

dengel build quote BUILD_ID --plan plan.toml

Review the plan and quote in the panel, where authorized people approve them and start paid work. See the managed Build quickstart.

Work from your terminal

Run dengel tui in an interactive terminal using your saved Dengel login. Use the arrow keys to move through items and see their previews, b for active Builds, and h for History. On a narrow terminal, Enter opens the preview and Esc returns to the same item. Press Enter on a build preview to follow its progress, or d for technical detail. Use / to find an item and ? for help.

Press o to open the selected item in the panel, where you review and approve work. Press y to copy and show the panel link. Over SSH, run dengel tui --no-browser to show the link without opening a browser.

Read and monitor work

Use the build ID from the panel's run URL, the Git project ID from its Code page, and the proposal or Receipt ID from the record you want to read. Each ID refers to a different resource.

Command Result
dengel status or dengel run List workspace runs.
dengel status --waiting Read the approval queue. Exit 4 means it contains an item.
dengel run BUILD_ID Read one run's state, including lifecycle, disposition, and verdict.
dengel run timeline BUILD_ID Read that run's ordered activity.
dengel proposal list --project PROJECT_ID List proposals for a Dengel Git project.
dengel proposal show --project PROJECT_ID PROPOSAL_ID Read the exact proposal, candidate, digests, checks, and Receipt summary when present.
dengel stack list --project PROJECT_ID List proposal stacks in a Git project.
dengel stack status --project PROJECT_ID --stack STACK_ID Read a specific stack and its revision.
dengel contract Read the Gateway capability inventory.
dengel receipt, dengel receipt --q TEXT, dengel receipt RECEIPT_ID List, search, or read a signed delivery Receipt.

Add --json for automation. Gateway-backed reads wrap the Gateway response inside the CLI's data field. For example, dengel --json receipt RECEIPT_ID returns the record at data.data.receipt and the Gateway source statuses at data.sources. dengel submit --json emits its own result object. See the API reference for source status handling.

Draft, review, and start a Build

Save a draft with dengel spec create --file idea.md --key first-save. Run dengel --json spec list to find drafts and dengel --json spec show SPEC_ID for the current revision. Edit the draft with dengel spec edit SPEC_ID --file idea.md --revision N --key edit-1. Reuse a key when retrying the same save. If the revision changed while you were editing, read it again before retrying.

Open the saved draft with dengel spec review SPEC_ID to choose the project and prepare the plan. For eligible managed builds, use dengel build autopilot BUILD_ID or press u on a build in the TUI. The panel recommends Autopilot and asks you to approve the exact scope and spending limit. Dengel builds, independently verifies and merges when the delivery gates pass. If it needs a decision, the build pauses in Inbox.

Use dengel build review BUILD_ID to review and approve the plan and price in your signed-in browser. Select Start later to approve now and start separately with dengel build start BUILD_ID. Add --no-browser to print the review links over SSH.

In the TUI, press s for Specs, then n or e to create or edit a draft in your terminal editor. Dengel uses VISUAL, EDITOR or vi. If the server has a newer revision, press x to save your text locally and use e to reopen the current draft. In Builds, press a to review the plan and price or g to open the Start building control.

Answer an Inbox question

Run dengel --json inbox to find an item, then use dengel inbox ITEM_ID --confirm. In the TUI, select a Needs You item and press a. Review the choices in your signed-in browser and save the decision. The terminal shows the recorded choice for that item. On SSH, add --no-browser and open the displayed review URL yourself.

Submit an agent change

For a workspace with Guard and CLI submission enabled, ask an owner or maintainer to approve the repository checks in Code, register the agent app, and issue a project submit token. Set up the checkout with a dengel remote pointing to the intended repository and provide the token through an approved Git credential helper that can return it without prompting. Keep the human Gateway token out of the agent session. From the checkout with the intended commit:

dengel --json submit --branch --project PROJECT_ID --agent codex --session SESSION_ID

Replace PROJECT_ID and SESSION_ID and use codex only if that is the registered app role. --branch submits the current commit and leaves uncommitted changes out. The client pushes the resolved commit to a candidate ref, then uses the submit token to open a proposal for that exact head. Read the returned proposal identity and hand it to the reviewer. If the proposal is refused after the push, the candidate ref can remain on the remote. The Guard quickstart also works with standard Git and panel review.

Propose a candidate that is already pushed

Use a delegated Gateway token and the exact remote commit ID:

dengel --json proposal create --project PROJECT_ID \
  --candidate-ref refs/heads/candidate/update-readme \
  --expected-head COMMIT_ID --idempotency-key update-readme-1

Use the same key for an exact retry. Review the proposed change in the panel. The managed Build and Guard quickstarts show how an authorized human starts verification and approves landing.

Exit codes

Exit How to handle it
0 Command completed. For submit, read the result to distinguish a proposal from nothing to submit. Check source statuses on Gateway reads.
1 Operational failure, such as missing configuration, unreadable input, transport trouble, or a server error. Inspect stderr.
3 The service refused the action. Read the response and resolve the permission, credential, or state problem before retrying.
4 inbox or status --waiting found an item, or inbox --confirm stopped waiting without seeing a recorded answer.

Invalid command syntax exits with code 2. Use the workflow and Receipts reference to interpret successful read results.

Git and Guard in the terminal

Create a private EU repository with dengel repo create --slug NAME --key KEY --acknowledge-storage. Use dengel repo show PROJECT_ID for the clone URL and configure Git access in the repository's panel. Use dengel repo configure-checks PROJECT_ID to open the approved-check editor in the panel, then push a candidate branch and create its proposal.

Use dengel proposal verify --project PROJECT_ID PROPOSAL_ID to review and start the quoted checks, and dengel proposal approve --project PROJECT_ID PROPOSAL_ID to review and merge after verification. Both open the exact proposal in your signed-in browser. Read the delivered record with dengel proposal receipt --project PROJECT_ID PROPOSAL_ID.

In dengel tui, press t for Repositories, p for Proposals, c for Checks, and v for signed receipts. In Proposals, press n to pick a pushed candidate, then review its commit and confirm. Press g to open its checks, a to open merge review, and o to open the receipt after it lands.

In the TUI, press w for workspace setup or select a repository and press l for stacks. The CLI offers dengel workspace github --no-browser and dengel stack review --project PROJECT_ID --stack STACK_ID --no-browser.

Guard and Autopilot reviews confirm the action in your signed-in browser. The terminal waits for the recorded outcome. Use --no-browser with a CLI review command to print its link and return immediately.