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.

npm install -g @devicai/cli
devic auth login --api-key devic-your-key
devic assistants chat support-assistant -m "Where is my order?"

---

Authentication

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.

---

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

Assistants

devic assistants list | get | chat, with conversation history and feedback.

Agents

devic agents … — CRUD, threads, approvals, pause and resume, evaluations, costs.

Tool servers

devic tool-servers … — MCP and custom servers, their tools, cloning.

Integrations and triggers

devic integrations … and devic triggers … — connect apps, pick tools, subscribe to events.

Knowledge and skills

devic documents …, devic skills … — read, write and install.

Projects

devic projects … — and --project on most listings.

Environments

devic environments … — the machine, its secrets, its snapshot and who is connected to it.

Sandboxes

devic sandbox start | exec | stop, plus ls, cat and write on a real Linux machine.

---

Reasoning effort

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 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:

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.

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:

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.

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 offers the same API as a typed client — including minting tenant sessions:

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:

npx skills add devicai/skills

See Skills.