@devicai/cli

CLI for the Devic AI Platform API. Agent-first — JSON output by default when piped, human-readable in terminal. Single runtime dependency (commander).

Installation

npm install -g @devicai/cli
# or
npx @devicai/cli <command>

Authentication

# Login with API key (validates with a test request, stores in ~/.config/devic/config.json)
devic auth login --api-key devic-xxx

# Check auth status
devic auth status

# Logout (removes stored credentials)
devic auth logout

Environment variables override stored config:

Global Options

Exit Codes

Errors are written to stderr. In JSON mode: {"error":"...","code":"..."}. In human mode: markdown-formatted error with bold label and inline code.

Human Output Format

When using -o human (or in a TTY), all output is markdown-formatted:

• Lists: Rendered as markdown tables with | Header | ... | format
• Details: Properties with **Bold Label:** value, IDs in `inline code`
• Conversations: Messages labeled **USER:** / **ASSISTANT:** / **TOOL:**
• Status indicators: [OK] success, [..] in-progress, [!!] needs attention, [XX] failed
• Actions: Success messages prefixed with [OK]
• Errors: Written to stderr with **Error:** message format
• Pagination: Footer with **Total:** N | **Offset:** N | ...
• Nested objects: Rendered as fenced JSON code blocks
• Thread tasks: Displayed as [x]/[ ] checklists

This format is designed for both human reading and LLM/agent consumption.

JSON Input

All create/update commands support --from-json <file> (or - for stdin) for complex payloads:

# From file
devic agents create --from-json agent-config.json

# From stdin
echo '{"name":"My Agent"}' | devic agents create --from-json -

Pagination

All list commands support:

Commands Reference

devic assistants

Manage assistants and chat conversations.

devic assistants list

List all assistant specializations.

devic assistants list [--external] [--offset <n>] [--limit <n>]

devic assistants get

Get details of a specific assistant.

devic assistants get <identifier>

devic assistants create

Create a new assistant.

devic assistants create [--name <name>] [--description <desc>] [--from-json <file>]

The --from-json payload supports all assistant specialization fields: name, description, presets, model, provider, imgUrl, state, availableToolsGroupsUids, enabledTools, accessConfiguration, widgetConfiguration, memoryDocuments, structuredOutput, guardrailsConfiguration, codeSnippetIds, availableSkillIds, subagentsIds, maxChatMessages, maxToolResponseInputTokens.

devic assistants update

Update an existing assistant (partial updates supported).

devic assistants update <identifier> [--name <name>] [--description <desc>] [--from-json <file>]

Same options as create. Only provided fields will be updated.

devic assistants delete

Delete an assistant.

devic assistants delete <identifier>

devic assistants chat

Send a message to an assistant. Uses async mode with polling by default.

devic assistants chat <identifier> -m "message" [options]

When --wait is active, status updates are emitted during polling:

• JSON mode (-o json): NDJSON lines on stdout:

  {"type":"chat_status","chatUid":"...","status":"processing","timestamp":1234567890}
  {"type":"chat_status","chatUid":"...","status":"completed","timestamp":1234567891}
  

• Human mode (-o human): Readable status lines on stderr:

  [..] Chat `550e8400...` — **processing**
  [OK] Chat `550e8400...` — **completed**
  

Chat polling: 1s initial interval, 1.5x backoff, 10s max, 5min timeout.

Status values: processing, completed, error, waiting_for_tool_response, handed_off.

Status indicators: [OK] completed/active, [..] processing/queued, [!!] paused/waiting, [XX] failed/error.

devic assistants stop

Stop an in-progress async chat.

devic assistants stop <identifier> <chatUid>

devic assistants chats list

List chat histories for an assistant.

devic assistants chats list <identifier> [--omit-content] [--offset <n>] [--limit <n>]

devic assistants chats get

Get a specific chat history.

devic assistants chats get <identifier> <chatUid>

devic assistants chats search

Search chat histories across all assistants with filters.

devic assistants chats search [options]

devic agents

Manage agents, execution threads, and costs.

devic agents list

devic agents list [--archived] [--offset <n>] [--limit <n>]

devic agents get

devic agents get <agentId>

devic agents create

devic agents create [--name <name>] [--description <desc>] [--from-json <file>]

The --from-json payload supports all agent fields: name, description, assistantSpecialization (with presets, availableToolsGroupsUids, enabledTools, model, provider, subagentsIds), provider, llm, maxExecutionInputTokens, maxExecutionToolCalls, evaluationConfig, subAgentConfig.

devic agents update

devic agents update <agentId> [--name <name>] [--description <desc>] [--from-json <file>]

devic agents delete

devic agents delete <agentId>

devic agents threads

Manage agent execution threads.

devic agents threads create

Create and optionally poll a new thread.

devic agents threads create <agentId> -m "task" [options]

When --wait is active, status updates are emitted during polling:

• JSON mode (-o json): NDJSON lines on stdout:

  {"type":"thread_status","threadId":"...","state":"processing","tasks":[...],"timestamp":1234567890}
  {"type":"thread_status","threadId":"...","state":"completed","tasks":[...],"timestamp":1234567891}
  

• Human mode (-o human): Readable status lines on stderr:

  [..] Thread `thread-456` — **processing** (tasks: 1/3)
  [OK] Thread `thread-456` — **completed** (tasks: 3/3)
  

Thread polling: 2s initial interval, 1.5x backoff, 15s max, 10min timeout.

Terminal states: completed, failed, terminated.

Actionable states (returned to caller): paused_for_approval.

devic agents threads list

devic agents threads list <agentId> [options]

devic agents threads get

devic agents threads get <threadId> [--with-tasks] [--grep <pattern>]

devic agents threads approve

devic agents threads approve <threadId> [-m "message"]

devic agents threads reject

devic agents threads reject <threadId> [-m "message"]

devic agents threads pause

devic agents threads pause <threadId>

devic agents threads resume

devic agents threads resume <threadId>

devic agents threads complete

Manually set a thread's final state.

devic agents threads complete <threadId> --state <COMPLETED|FAILED|CANCELLED|TERMINATED>

devic agents threads evaluate

Trigger AI evaluation of a completed thread.

devic agents threads evaluate <threadId>

devic agents costs

Track agent execution costs.

devic agents costs daily

devic agents costs daily <agentId> [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD]

devic agents costs monthly

devic agents costs monthly <agentId> [--start-month YYYY-MM] [--end-month YYYY-MM]

devic agents costs summary

Get today's and current month's cost summary.

devic agents costs summary <agentId>

devic tool-servers

Manage tool servers, their definitions, and individual tools.

devic tool-servers list

devic tool-servers list [--offset <n>] [--limit <n>]

devic tool-servers get

devic tool-servers get <toolServerId>

devic tool-servers create

devic tool-servers create [--name <name>] [--url <url>] [--description <desc>] [--from-json <file>]

The --from-json payload supports: name, description, url, identifier, enabled, mcpType, toolDefinitions, authenticationConfig, imageUrl.

devic tool-servers update

devic tool-servers update <toolServerId> [--name <name>] [--url <url>] [--description <desc>] [--enabled <bool>] [--from-json <file>]

devic tool-servers delete

devic tool-servers delete <toolServerId>

devic tool-servers clone

devic tool-servers clone <toolServerId>

devic tool-servers definition

Get the full tool server definition.

devic tool-servers definition <toolServerId>

devic tool-servers update-definition

devic tool-servers update-definition <toolServerId> --from-json <file>

devic tool-servers tools

Manage individual tools within a tool server.

devic tool-servers tools list

devic tool-servers tools list <toolServerId>

devic tool-servers tools get

devic tool-servers tools get <toolServerId> <toolName>

devic tool-servers tools add

devic tool-servers tools add <toolServerId> --from-json <file>

JSON structure:

{
  "type": "function",
  "function": {
    "name": "tool_name",
    "description": "What it does",
    "parameters": {
      "type": "object",
      "properties": { "param": { "type": "string" } },
      "required": ["param"]
    }
  },
  "endpoint": "/api/path/${param}",
  "method": "GET",
  "pathParametersKeys": ["param"]
}

devic tool-servers tools update

devic tool-servers tools update <toolServerId> <toolName> --from-json <file>

devic tool-servers tools delete

devic tool-servers tools delete <toolServerId> <toolName>

devic tool-servers tools test

Test a tool call with parameters.

devic tool-servers tools test <toolServerId> <toolName> --from-json <file>

The JSON file should contain the parameters object: {"city": "London"}.

devic feedback

Submit and view feedback on chat messages and thread messages.

devic feedback submit-chat

devic feedback submit-chat <identifier> <chatUid> --message-id <id> [options]

devic feedback list-chat

devic feedback list-chat <identifier> <chatUid>

devic feedback submit-thread

devic feedback submit-thread <threadId> --message-id <id> [options]

Same options as submit-chat.

devic feedback list-thread

devic feedback list-thread <threadId>

Usage Examples

Send a message and get the result

# Simple chat
devic assistants chat default -m "What is the capital of France?"

# Continue a conversation
CHAT_UID=$(devic assistants chat default -m "Hello" -o json | jq -r '.chatUID')
devic assistants chat default -m "Tell me more" --chat-uid "$CHAT_UID"

Create an agent and run a thread

# Create agent from JSON
cat <<'EOF' | devic agents create --from-json -
{
  "name": "Data Analyst",
  "description": "Analyzes data and creates reports",
  "assistantSpecialization": {
    "presets": "You are a data analyst. Analyze data and provide insights.",
    "model": "gpt-4o"
  }
}
EOF

# Run a thread and wait for completion
devic agents threads create <agentId> -m "Analyze Q4 sales data" --wait

Handle thread approvals in a script

# Create thread
RESULT=$(devic agents threads create <agentId> -m "Delete old records" --wait -o json)
STATE=$(echo "$RESULT" | jq -r '.state')

if [ "$STATE" = "paused_for_approval" ]; then
  THREAD_ID=$(echo "$RESULT" | jq -r '._id')
  devic agents threads approve "$THREAD_ID" -m "Approved"
fi

Set up a tool server with tools

# Create tool server
cat <<'EOF' | devic tool-servers create --from-json -
{
  "name": "Weather API",
  "url": "https://api.weather.example.com",
  "toolDefinitions": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather for a city",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    },
    "endpoint": "/weather/${city}",
    "method": "GET",
    "pathParametersKeys": ["city"]
  }]
}
EOF

# Test the tool
echo '{"city":"London"}' | devic tool-servers tools test <serverId> get_weather --from-json -

Search for specific data in agent threads

# List threads without content (fast, metadata only)
devic agents threads list <agentId> --omit-content --limit 50

# Find a specific email within a thread's content
devic agents threads get <threadId> --grep "user@example.com"

# Combine: list threads, then search each for a keyword
devic agents threads list <agentId> --omit-content -o json | \
  jq -r '.[].threadId' | \
  while read tid; do
    RESULT=$(devic agents threads get "$tid" --grep "target@email.com" -o json)
    COUNT=$(echo "$RESULT" | jq '.threadContent | length')
    if [ "$COUNT" -gt "0" ]; then echo "Found in thread: $tid"; fi
  done

Pipe JSON between commands

# Get all completed threads and their evaluations
devic agents threads list <agentId> --state COMPLETED -o json | \
  jq -r '.[].threadId' | \
  while read tid; do devic agents threads evaluate "$tid"; done