# d1v.ai Agent README

This document is the machine-readable operating guide for AI coding agents working with d1v.ai and d1v CLI.

## Product model

- d1v.ai is an Agent workspace for defining tasks, running coding agents, inspecting execution, and reviewing results.
- A project can use a cloud runtime or a paired local runtime.
- Existing sessions remain pinned to the runtime where they started.
- The local agent opens an outbound connection to d1v.ai. Normal runtime control does not require an inbound port on the developer machine.

## Safety rules

1. Never print, log, upload, or commit API keys, auth tokens, passwords, or local `.env` files.
2. Treat preview and production as separate environments. Validate with test credentials before replacing them with production credentials.
3. Inspect the current repository and its `AGENTS.md`, `README.md`, and project plan before editing.
4. Prefer structured output with `--format json` when a command is consumed by automation.
5. Verify command exit status and resulting state. Do not infer success from terminal text alone.
6. Do not silently fall back from an unavailable local runtime to a cloud runtime.

## Install and verify

```bash
curl -fsSL https://d1v.ai/install/d1v-cli.sh | bash
d1v --version
d1v runtime doctor
```

The installer downloads a release archive from GitHub and verifies its SHA-256 checksum before installation.

Alternative installation methods:

```bash
brew install d1v-ai/tap/d1v
cargo binstall d1v-cli
cargo install --locked d1v-cli
```

## Authenticate and inspect

```bash
d1v auth login
d1v auth status
d1v project list --format json
d1v github status
```

For non-interactive automation, provide credentials through a secret manager. Supported variables include `D1V_API_KEY`, `D1V_AUTH_TOKEN`, and `D1V_BASE_URL`.

## Pair and start a local runtime

```bash
d1v runtime doctor
d1v agent pair
d1v agent start
d1v agent status
```

When the web UI supplies a pairing code:

```bash
d1v agent pair --code <pairing-code>
```

Bind an existing local directory to a project:

```bash
d1v agent project bind --project-id <project_id> --path ~/work/my-app
```

Create or import a local project directory when required:

```bash
d1v agent project create --project-id <project_id> --name my-app
d1v agent project import --path ~/work/my-app --project-id <project_id>
```

## Expose a local HTTP service

```bash
d1v expose 3000
d1v expose list
d1v expose close <binding_id>
```

The free CLI expose path is intended for temporary HTTP development traffic. Keep authentication enabled in the application and do not expose private admin or database interfaces.

## Diagnostics and maintenance

```bash
d1v runtime doctor
d1v config show
d1v upgrade
d1v uninstall
```

Useful environment variables:

- `D1V_FORMAT`: default output format, such as `json`
- `D1V_LANG`: output language
- `D1V_LOG_FILE`: diagnostic log destination
- `NO_COLOR`: disable terminal color
- `RUST_LOG`: log filtering

## Canonical references

- Install guide: https://d1v.ai/cli-install
- CLI documentation: https://d1v.ai/docs/cli
- Core concepts: https://d1v.ai/docs/concepts
- Public expose: https://d1v.ai/docs/expose
- Documentation index: https://d1v.ai/docs
- CLI source and releases: https://github.com/d1vai/d1v-cli
- OpenAPI viewer: https://d1v.ai/openapi