shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

devic-cli

@devicai/cli参考 —— Devic AI平台的命令行界面。在从命令行执行Devic API操作、脚本自动化或构建与助手、代理、工具服务器和反馈交互的工作流时使用。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

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

| Variable | Description | |----------|-------------| | DEVIC_API_KEY | API key | | DEVIC_BASE_URL | API base URL (default: https://api.devic.ai) |

Global Options

| Option | Description | |--------|-------------| | -o, --output <format> | Output format: json or human. Auto-detected: JSON when piped, human in TTY | | --base-url <url> | API base URL. Overrides config and env var. Priority: --base-url flag > DEVIC_BASE_URL env > config file > https://api.devic.ai | | -V, --version | Show version | | -h, --help | Show help |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Error | | 2 | Authentication required | | 3 | Poll timeout |

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:

| Option | Default | Description | |--------|---------|-------------| | --offset <n> | 0 | Items to skip | | --limit <n> | 10 | Max items (max 100) |

Commands Reference

devic assistants

Manage assistants and chat conversations.

devic assistants list

List all assistant specializations.

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

| Option | Description | |--------|-------------| | --external | Only show externally accessible assistants |

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

| Option | Description | |--------|-------------| | --name <name> | Assistant name | | --description <desc> | Assistant description | | --from-json <file> | Read full assistant config from JSON file (- for stdin) |

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, contextManagement ({ fullContextTurnDepth?: number, alwaysIncludeUserMessages?: boolean } — send only the most recent N turns in full and summarize older ones).

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]

| Option | Description | |--------|-------------| | -m, --message <text> | Required. Message to send | | --chat-uid <uid> | Continue an existing conversation | | --provider <provider> | LLM provider override (openai, anthropic, azure, google) | | --model <model> | Model override | | --tags <tags> | Comma-separated tags | | --wait | Async mode + poll for result (default: true) | | --no-wait | Synchronous mode — blocks until response | | --from-json <file> | Read full ProcessMessageDto from file (- for stdin) |

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]

| Option | Description | |--------|-------------| | --assistant <identifier> | Filter by assistant | | --tags <tags> | Comma-separated tags | | --start-date <date> | Start date (ISO string) | | --end-date <date> | End date (ISO string) | | --omit-content | Exclude chat content | | --from-json <file> | Read filters from file |

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, contextManagement), 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]

| Option | Description | |--------|-------------| | -m, --message <text> | Required. Initial message/task | | --tags <tags> | Comma-separated tags | | --wait | Poll until terminal state | | --from-json <file> | Read thread config from file |

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]

| Option | Description | |--------|-------------| | --state <state> | Filter by state | | --start-date <date> | Start date filter | | --end-date <date> | End date filter | | --date-order <order> | Sort: asc or desc | | --tags <tags> | Comma-separated tags | | --omit-content | Exclude thread content from response (returns metadata and state only). Significantly reduces payload size for large thread lists |

devic agents threads get

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

| Option | Description | |--------|-------------| | --with-tasks | Include task details | | --grep <pattern> | Filter thread content to only show messages matching the pattern (case-insensitive). Useful for finding specific data within large threads without scanning the full content manually |

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 documents

Manage knowledge documents (markdown). List, read, create, update and manage versions.

devic documents list [--project <p>] [--folder <id>] [--file-type md]
devic documents get <documentId>
devic documents create --name <name> [content source]
devic documents update <documentId> [fields...]
devic documents versions list <documentId>
devic documents versions revert <documentId> <version>

Providing document content (create / update)

The markdown body is never read from a shell redirect by itself. You must pass it through one of these content sources:

| Source | Example | |--------|---------| | Inline | devic documents update <id> --content "# Title\n..." | | From a file | devic documents update <id> --from-file SKILL.md | | From stdin (pipe) | cat SKILL.md \| devic documents update <id> --from-stdin |

⚠️ Do NOT use devic documents update <id> < file.md on its own. A bare shell redirect is only picked up when the process detects a piped stdin; the reliable forms are --from-file <path> or a real pipe with --from-stdin. To avoid silent mistakes, update now refuses an empty payload (it errors out instead of returning a misleading success), and the response includes versionCreated: true|false so you can confirm a new version was actually written. Always check that flag after updating.

update only creates a new version when the content actually changes; updating with identical content (or only metadata like --name/--folder) reports versionCreated: false.

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]

| Option | Description | |--------|-------------| | --message-id <id> | Required. Message UID to give feedback on | | --positive | Positive feedback (thumbs up) | | --negative | Negative feedback (thumbs down) | | --comment <text> | Feedback comment | | --from-json <file> | Read full feedback payload from file |

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