> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Devic CLI

> The whole public API from a terminal, built for scripts and for coding agents.

`@devicai/cli` wraps the Devic public API in a command-line tool. It is agent-first: structured JSON by default when piped, machine-readable errors, meaningful exit codes and polling that does not block forever.

```bash theme={null}
npm install -g @devicai/cli
devic auth login --api-key devic-your-key
devic assistants chat support-assistant -m "Where is my order?"
```

![The Devic CLI](https://mintcdn.com/devic/DKyKkxiOLW4okLYC/images/cli/session.png?fit=max\&auto=format\&n=DKyKkxiOLW4okLYC\&q=85\&s=a5152437ce85eaf3d358d080676b36aa)

***

## Authentication

```bash theme={null}
devic auth login --api-key devic-your-key
devic auth status

# or, taking precedence over stored credentials
export DEVIC_API_KEY=devic-your-key
export DEVIC_BASE_URL=https://api.devic.ai
```

Credentials live in `~/.config/devic/config.json`. Get a key from [API keys](https://docs.devic.ai/devic/administration/api-keys.md).

***

## Output

Human-readable tables in a terminal, JSON when piped or non-interactive. Force either with `--output json` / `--output human`.

Errors always go to stderr as JSON — `{"error":"…","code":"…"}` — and the exit code says what happened: `0` success, `1` error, `2` authentication required, `3` poll timeout.

***

## What it covers

> [card] Assistants
>
> `devic assistants list | get | chat`, with conversation history and feedback.

> [card] Agents
>
> `devic agents …` — CRUD, threads, approvals, pause and resume, evaluations, costs.

> [card] Tool servers
>
> `devic tool-servers …` — MCP and custom servers, their tools, cloning.

> [card] Integrations and triggers
>
> `devic integrations …` and `devic triggers …` — connect apps, pick tools, subscribe to events.

> [card] Knowledge and skills
>
> `devic documents …`, `devic skills …` — read, write and install.

> [card] Projects
>
> `devic projects …` — and `--project` on most listings.

> [card] Environments
>
> `devic environments …` — the machine, its secrets, its snapshot and who is connected to it.

> [card] Sandboxes
>
> `devic sandbox start | exec | stop`, plus `ls`, `cat` and `write` on a real Linux machine.

***

## Reasoning effort

```bash theme={null}
devic models list --provider open-ai
devic assistants update "$ASSISTANT_ID" --reasoning-effort high
devic assistants chat "$ASSISTANT_ID" -m "Review" --conversation-reasoning-effort low --reasoning-effort high
devic assistants chat "$ASSISTANT_ID" --chat-uid "$CHAT_UID" -m "Continue" --conversation-reasoning-effort default
```

Effort flags support assistant defaults, conversation defaults and individual
turns. `default` restores inheritance; `none` is an explicit model level.
See [reasoning effort](https://docs.devic.ai/devic/assistants/reasoning-effort.md) for supported-level
discovery, JSON fields, precedence and reset behavior.

***

## Scheduling an agent

An agent can run itself. There is no external cron to set up, and the three
scheduling modes are mutually exclusive:

```bash theme={null}
devic agents create --name "Daily report" --cron "0 7 * * 1-5" --timezone Europe/Madrid
devic agents update <agentId> --schedule-at 09:00 --days monday,friday --timezone Europe/Madrid
devic agents update <agentId> --every-days 14 --at 08:30 --start-date 2026-01-06
devic agents update <agentId> --no-schedule
```

***

## Provisioning a machine

Environments and sandboxes take the environment by id **or by name**, and the
sandbox commands find the live session on their own after `start`.

```bash theme={null}
devic environments create --name "Reporting box" --runtime python3.13 \
  --env "DATABASE_URL=postgres://..." --init-script-file ./provision.sh --snapshots
devic environments snapshot init "Reporting box"

devic sandbox start "Reporting box" --timeout 15
devic sandbox exec "Reporting box" 'cd /workspace && ./report.sh | tail -20'
devic sandbox stop "Reporting box"          # this is what saves the snapshot
```

Secrets belong in `--env`: they are encrypted at rest, injected into the machine
as ordinary environment variables, and always read back masked. `--env` merges
over what is stored, so adding one variable does not destroy the others.

***

## Following a long run

`--wait` blocks until a run finishes, which is fine at a keyboard and wrong for an agent driving the CLI from a sandbox, where commands are killed after about 45 seconds.

`watch` is the incremental alternative. It looks for a short window, reports **only what changed since the previous call**, and says whether watching further is worth it:

```bash theme={null}
devic agents threads watch <threadId> --wait 5 --window 35 --interval 3
devic assistants chats watch <chatUid> --assistant <identifier> --window 35
```

The exit code is the decision:

| Code | Meaning |
| - | - |
| `0` | Finished. |
| `10` | A human has to approve or reject — nothing moves until then. |
| `11` | Blocked on something external: waiting for a response, paused, out of allowance. |
| `12` | Still running. Call again with the returned cursor. |
| `13` | Nothing changed across several checks. |

Alongside them, `advice` carries a recommended cadence and `diagnostics` explains *why* a run is not moving — a disabled agent, one at its concurrency limit, a queue delay, a pending approval, a scheduled resume.

> [!TIP]
>
> This is what makes the CLI usable as a tool for a coding agent: it can start work, come back, and be told exactly what changed and what to do next, without holding a process open.

***

## Server-side SDK

For Node backends, [`@devicai/sdk`](https://www.npmjs.com/package/@devicai/sdk) offers the same API as a typed client — including minting [tenant sessions](https://docs.devic.ai/devic/multi-tenant/tenant-sessions.md):

```ts theme={null}
import { Devic } from '@devicai/sdk';

const devic = new Devic({ apiKey: process.env.DEVIC_API_KEY });
const session = await devic.auth(organisationId, userId).session();
```

***

## Skills for coding assistants

If you work with an AI coding assistant, install the Devic skills so it knows these APIs properly:

```bash theme={null}
npx skills add devicai/skills
```

See [Skills](https://docs.devic.ai/devic/skills/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.