# Install and use the Diakrin CLI

> Install the diakrin command, sign in and work with your apps from a terminal or coding agent.

Source: https://diakrin.com/docs/cli

The `diakrin` command lets you and your coding agent work with Diakrin from a terminal. It uses the same organization, app permissions and approvals as the console. It never gives you more access than you already have.

## Before you start

- macOS or Linux (Intel/AMD or ARM). Windows is not supported yet.
- Sign-in is stored in macOS Keychain or Linux Secret Service.
- Nothing else. The installer brings its own Node.js runtime and needs no GitHub account, token or administrator rights.

## Install

Open Terminal and run:

```sh
curl -fsSL https://diakrin.com/cli/install.sh | sh
```

Open a new terminal, then check that it runs:

```sh
diakrin --version
```

The installer checks the download against the release's SHA-256 checksums before it unpacks anything, installs into `~/.diakrin` and adds `diakrin` to `~/.local/bin`. To update later, run `diakrin upgrade` (or run the same line again); `diakrin upgrade --check` only looks, and `diakrin upgrade --to X.Y.Z` picks a version. The CLI tells you on a terminal when a newer version exists: it checks at most once a day, stays silent when you are offline, and never prints in scripts or CI. Set `DIAKRIN_NO_UPDATE_CHECK=1` to turn it off; `diakrin --version` prints the installed version; `diakrin --json --version` adds the latest version when known. To install a specific version, add `-s -- --version 0.1.2` after `sh`. To remove it, run `diakrin auth logout`, then delete `~/.diakrin` and `~/.local/bin/diakrin`.

IT and security teams can verify each release's Sigstore signature. See [diakrin.com/cli](https://diakrin.com/cli).

> Never put a Diakrin token or a password into project files, chat or command arguments.

## Sign in to a self-hosted installation

Your IT team gives you your company's Diakrin address, for example `int.example.com`. Sign in once:

```sh
diakrin auth login --host int.example.com
```

Your browser opens your company's Diakrin page. Sign in and choose **Allow**. Later commands remember the address. Check with `diakrin auth status`.

> [!SELF-HOSTED]
> Your installation is its own sign-in server. You do not need an app ID, sign-in origin or public key, and nothing is sent to Diakrin's hosted service.

## Sign in

Pick one of these. Both open your company sign-in in the browser.

**Connect a terminal to one app.** This is the simplest option. Copy the app ID from the app's page in the console, then run:

```sh
diakrin auth pair --api https://api.diakrin.com --app YOUR_APP_ID --name "My laptop"
```

Check that the app name and the confirmation code in the browser match your terminal, then approve. The session reaches only that app.

**Sign in as yourself.** This reaches every app you can access. IT provides the sign-in origin and public key. These are not secrets.

```sh
diakrin auth login --api https://api.diakrin.com --auth-origin YOUR_SIGN_IN_ORIGIN --public-key YOUR_PUBLIC_KEY
diakrin auth whoami
```

Use `--no-browser` to print the sign-in link instead of opening a browser.

## Choose your organization and app

```sh
diakrin organization list
diakrin context set --api https://api.diakrin.com --organization YOUR_ORGANIZATION_ID
diakrin app select --name "Team requests"
diakrin context show
```

> [!SELF-HOSTED]
> Leave out `--api`. Your installation's address was saved when you signed in.

`app select` accepts an exact name or ID. It never guesses between similar names. Saved selections are only defaults; your access is checked on every request.

## Common tasks

| Task | Command |
|---|---|
| Start a new app from a description | `diakrin app start --name "Team requests" --description "Track requests for our team"` |
| List apps you can access | `diakrin app list` |
| See saved drafts | `diakrin draft list` |
| See your app's latest version and its Preview | `diakrin app status` |
| Publish your latest saved version (another administrator approves) | `diakrin app publish` |
| Go back to the version that was live before | `diakrin app rollback --version-id VERSION_ID` |
| Follow a build or deployment | `diakrin operation watch --kind build --operation-id OPERATION_ID` |
| Read an app's recent errors (one hour at most, codes and IDs only) | `diakrin app observations read --app APP_ID --environment ENVIRONMENT_ID --kind logs --start 2026-10-24T09:00:00Z --end 2026-10-24T10:00:00Z` |
| See every command and its inputs | `diakrin schema` |
| Get help for one command | `diakrin app start --help` |

On a self-hosted installation whose apps are private (no sign-in), `diakrin app start` creates your app from the installation's starter, the private synthetic workspace: a fixed screen with example data. Its code under `src/` belongs to the template and cannot be changed, and it does not run on your computer (the CLI says so). Your first `diakrin save` sends it toward Preview. `diakrin capabilities --online` shows the starter under `journey.starter`, and the app, repository and version IDs appear in the `app start` result and on the console app page.

`app start` saves a draft and returns the next business questions. A draft is not a deployed app. Building, previewing and publishing follow the same reviews and approvals as in the console. See [Review capabilities and deployment](/docs/governance).

Add `--dry-run` to check a command's input without sending it. Add `--json` for machine-readable output. If a command's result is uncertain, check the current state first and reuse the same request key. Do not just run it again.

## What happens after you save

Saving is the last step you start. When you (or your agent) run `diakrin save --message "What changed"`, Diakrin does the rest in order:

1. **Check.** The version is built and started with a test database. You see `Checked ✓ (version N)` or the findings to fix.
2. **Image.** After a passed check, Diakrin publishes the version's image to your company cloud. Nothing to do; it is never shown as "ready".
3. **Preview.** Diakrin takes the version to your private Preview.

The console shows each version's Preview state in these words:

- **Preview queued**, **Checking**, **Building the preview**, **Starting the preview**: still on its way; the page looks again every few seconds.
- **Preview ready**: the link appears, labelled **Private link · no sign-in** or **Needs Diakrin sign-in**.
- **Preview didn't start**: something to fix, with the reason after **To fix:**. Your version is saved.
- **Preview status unknown**: Diakrin cannot confirm the Preview right now. No link is shown.
- **Preview shows an earlier version**: the Preview is out of date. No link is shown.

Read the status in either place:

- `diakrin save` prints the check result and one line about the Preview (add `--json` for your agent).
- The app's page in the console, under **Saved versions**, shows the check, image and Preview state per version.

A link appears only when the state is **Preview ready** and that exact version passed its health and audience checks. A saved or published image alone never shows ready. If a newer version fails, the page keeps the link to the last version that is ready, for example "Version 7 is still your live Preview". If the state says IT must act (for example, prepare the app's private Preview), your app is saved and nothing is lost; ask IT. A saved version that changes `package.json` or `pnpm-lock.yaml` is not previewed: the starter pins its dependencies, so revert that change and save again.

> [!SELF-HOSTED]
> Your Preview is a private address on your company network and opens without a sign-in. Whether Preview runs automatically depends on your installation; `diakrin capabilities --online` tells you.

## Use the CLI with your coding agent

Install the CLI on the same machine as your coding tool and sign in once. Ask your agent to use `diakrin --json` and to read `diakrin schema` before running a command. The agent can only do what your session allows. You still approve anything that needs an approval.

## Shell completion

```sh
diakrin completion zsh > _diakrin
diakrin completion bash > diakrin.bash
diakrin completion fish > diakrin.fish
```

Put the file in your shell's completion directory and restart the shell.

## Sign out and manage sessions

```sh
diakrin auth sessions
diakrin auth revoke --id SESSION_ID
diakrin auth logout
```

`logout` removes the session from this computer. Use `auth revoke` to end a session on the server, for example for a lost laptop.

## Troubleshooting

| Problem | What to do |
|---|---|
| `checksum mismatch` or `signature verification failed` | The download was changed or damaged and was not installed. Run the line again; if it repeats, tell IT. |
| `unsupported operating system` or `unsupported processor` | The CLI runs on macOS and Linux (x64, arm64). Windows is not supported yet. |
| `diakrin: command not found` | Open a new terminal. If it persists, add `~/.local/bin` to your PATH (`export PATH="$HOME/.local/bin:$PATH"`). |
| Sign-in is not saved between commands | Your system has no supported credential store, so the session lasts only for one process. Use `auth pair` within the same command run, or install the credential store. |
| Access denied | Your role or app access does not allow this action. Ask the app owner or IT. See [Troubleshooting and help](/docs/troubleshooting). |

To share details with support, run `diakrin support bundle --destination /absolute/path/support.json`. It writes a local file without credentials, source or business data and sends nothing.
