---
name: d1v
description: Operate d1v.ai projects and container workspaces with the d1v CLI. Use when a task involves D1V authentication, projects, interactive container shells, remote command execution, runtimes, workspace files, agent sessions, GitHub integration, environment variables, or deployments.
---

# d1v CLI

Use the installed `d1v` command. Prefer `--format json` whenever output will be parsed.

## Safety

- Never print, log, commit, or add API keys and tokens to command output, source files, or repository configuration.
- Inspect project and authentication state before changing anything.
- Confirm with the user before deleting a project, overwriting remote work, or deploying to production.
- Treat Preview and production as separate environments.
- Check the command exit code and then query resulting state; do not infer success from a submitted request.

## Authenticate and discover

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

If authentication is missing, ask the user to run `d1v auth login`. For an API key supplied securely on standard input, use `d1v auth login --api-key`.

## Projects and workspaces

```bash
d1v project templates --format json
d1v project create --name <name> --description <description> --format json
d1v project get <project_id> --format json
d1v init . --project-id <project_id>
d1v pull --dry-run --format json
d1v pull
d1v push --dry-run --format json
d1v push
```

Run dry-run first for pull and push. Inspect repository instructions and local changes before synchronization.

## Sessions

```bash
d1v session run <project_id> --prompt <task> --format json
d1v session status <project_id> --format json
d1v session history <project_id> --format json
```

Use the returned session identifier to inspect or cancel an execution. Do not start duplicate sessions for the same task without checking active sessions first.

## Container shell and command execution

Use an interactive shell only when a person needs to work directly in the container:

```bash
d1v shell
d1v shell <project_id>
d1v shell --organization-id <organization_id>
```

- With no target, `d1v shell` opens the personal workspace root.
- A positional project ID opens that project's directory. The control plane resolves its personal or organization workspace; do not also pass `--organization-id`.
- `--organization-id` opens the authorized organization workspace root and cannot be combined with a project ID.
- Interactive shells require a TTY and text output. Do not use `--format json` with `d1v shell`.

For automation, agent actions, CI, or any command whose output or exit status must be captured, use `d1v exec` and place the remote argv after `--`:

```bash
d1v exec -- git status --short
d1v exec --project-id <project_id> -- npm test
d1v exec --organization-id <organization_id> -- pwd
d1v --format json exec --project-id <project_id> -- sh -c 'printf ok; printf problem >&2; exit 7'
```

Prefer JSON for agent-readable execution results. Read `stdout`, `stderr`, `cwd`, and `exit_code`, and preserve a non-zero remote exit as a failed action. Use text mode when streaming output is important. Do not wrap commands in `sh -c` unless shell syntax such as pipes or redirection is required.

Shell access uses a short-lived, single-use ticket. Never print, persist, forward, or place the ticket in a URL, command argument, log, transcript, or generated file. Let the CLI negotiate direct-node versus backend-relay transport; do not reconstruct terminal WebSocket URLs manually.

## Environment variables

```bash
d1v env list --project <project_id> --format json
d1v env set --project <project_id> KEY=VALUE
d1v env export --project <project_id> --output .env.d1v
```

Never echo secret values. Use the CLI's supported input mechanism and keep generated files out of version control.

## Deployments

```bash
d1v deploy preview <project_id> --format json
d1v deploy status <project_id> --format json
d1v deploy history <project_id> --format json
```

After requesting Preview, poll status until it reaches a terminal state and report the resulting URL or error. Use `d1v deploy prod` only after explicit user confirmation.

## Local runtime

```bash
d1v runtime doctor --format json
d1v agent status --format json
d1v agent pair
d1v agent start
```

Do not silently switch execution from a requested local runtime to cloud when the local runtime is unavailable.

## References

- https://www.d1v.ai/cli-install
- https://www.d1v.ai/docs/cli
- https://www.d1v.ai/openapi