sevdesk-agent-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sevdesk-agent-cli

When to use

适用场景

Use this skill when tasks involve sevdesk API access from this workspace, especially when an agent must:

inspect business/accounting state via read-only endpoints,
execute write endpoints with explicit guard confirmations,
produce a context snapshot for later agent runs.

当工作流中需要从当前工作区访问Sevdesk API时，可使用此Skill，尤其是在Agent需要执行以下操作的场景：

通过只读端点查看业务/财务状态，
在明确确认保护机制后执行写入端点操作，
生成上下文快照供后续Agent运行使用。

Preconditions

前置条件

CLI is runnable, either:
- from a checkout of this repo:
```
npm install && npm run build
```
  (then run
```
sevdesk-agent ...
```
  ), or
- via npx (no local build, run from outside this repo folder):
```
npx -y -p @codecell-germany/sevdesk-agent-skill sevdesk-agent --help
```
API token is available in env:
- ```
SEVDESK_API_TOKEN=<token>
```

Optional env:

SEVDESK_BASE_URL

(default

https://my.sevdesk.de/api/v1

)

```
SEVDESK_USER_AGENT
```
```
SEVDESK_ALLOW_WRITE=true
```
(required for write execution)

CLI可正常运行，两种方式可选：
- 从本仓库检出后运行：
```
npm install && npm run build
```
  （之后执行
```
sevdesk-agent ...
```
  ），或
- 通过npx运行（无需本地构建，在本仓库目录外执行）：
```
npx -y -p @codecell-germany/sevdesk-agent-skill sevdesk-agent --help
```
环境变量中需配置API令牌：
- ```
SEVDESK_API_TOKEN=<token>
```

可选环境变量：

SEVDESK_BASE_URL

（默认值为

https://my.sevdesk.de/api/v1

）

```
SEVDESK_USER_AGENT
```
```
SEVDESK_ALLOW_WRITE=true
```
（执行写入操作时必填）

Core workflow

核心工作流

Discover operation ids:

```
sevdesk-agent ops list --read-only
```
```
sevdesk-agent op-show <operationId>
```
```
sevdesk-agent ops-quirks
```

Run read calls first:
- ```
sevdesk-agent read <operationId> --query key=value
```
- by default, read responses are normalized for known live API quirks
- Shell quoting: params like
```
contact[id]
```
  should be quoted:
```
--query 'contact[id]=123'
```
- Invoice date filters (observed): in our tests,
```
getInvoices
```
  works with
```
startDate
```
  /
```
endDate
```
  as Unix timestamps (seconds). ISO dates like
```
2026-01-01
```
  may return empty results. Example:
```
sevdesk-agent read getInvoices --query startDate=1767225600 --query endDate=1769903999 --output json
```
- Generate a full read-op reference doc:
```
sevdesk-agent docs read-ops --output knowledge/READ_OPERATIONS.md
```

For write calls, only with explicit confirmation:

sevdesk-agent write <operationId> --execute --confirm-execute yes --allow-write ...

Persist agent handoff context:

stdout (default):
```
sevdesk-agent context snapshot
```

optional file export:

sevdesk-agent context snapshot --output .context/sevdesk-context-snapshot.json

查看操作ID：

```
sevdesk-agent ops list --read-only
```
```
sevdesk-agent op-show <operationId>
```
```
sevdesk-agent ops-quirks
```

优先执行只读调用：
- ```
sevdesk-agent read <operationId> --query key=value
```
- 默认情况下，只读响应会针对已知的实时API特性进行标准化处理
- Shell引号规则：类似
```
contact[id]
```
  的参数需要加引号：
```
--query 'contact[id]=123'
```
- 发票日期过滤（实测情况）：在我们的测试中，
```
getInvoices
```
  接口支持以Unix时间戳（秒）作为
```
startDate
```
  /
```
endDate
```
  参数。使用ISO格式日期如
```
2026-01-01
```
  可能会返回空结果。示例：
```
sevdesk-agent read getInvoices --query startDate=1767225600 --query endDate=1769903999 --output json
```
- 生成完整的只读操作参考文档：
```
sevdesk-agent docs read-ops --output knowledge/READ_OPERATIONS.md
```

写入调用（需明确确认）：

sevdesk-agent write <operationId> --execute --confirm-execute yes --allow-write ...

持久化Agent交接上下文：

默认输出到标准输出：
```
sevdesk-agent context snapshot
```

可选导出到文件：

sevdesk-agent context snapshot --output .context/sevdesk-context-snapshot.json

Guardrails

防护机制

Default behavior is safe: non-GET calls are blocked unless all write guards are set.
In production workflows, prefer read-only tests and read-only probes first.
For
```
*GetPdf
```
endpoints, responses are typically JSON wrapped in
```
data.objects
```
(often containing
```
filename
```
,
```
mimetype
```
, and base64
```
content
```
). The CLI does not automatically write files to disk.
If the server returns a non-JSON binary content-type (pdf/xml/zip/csv), the CLI prints metadata (
```
binary
```
,
```
bytes
```
,
```
contentType
```
) instead of raw bytes.
Runtime-required query quirks are enforced for selected operations (e.g.
```
contactCustomerNumberAvailabilityCheck
```
requires
```
customerNumber
```
at runtime).
Use
```
op-show
```
or
```
ops-quirks
```
to see operation-specific runtime quirks.

默认行为为安全模式：非GET调用会被拦截，除非所有写入保护机制都已配置。
在生产工作流中，建议优先执行只读测试和只读探测。
对于
```
*GetPdf
```
端点，响应通常是包裹在
```
data.objects
```
中的JSON（通常包含
```
filename
```
、
```
mimetype
```
和base64格式的
```
content
```
）。CLI不会自动将文件写入磁盘。
如果服务器返回非JSON的二进制内容类型（如pdf/xml/zip/csv），CLI会打印元数据（
```
binary
```
、
```
bytes
```
、
```
contentType
```
）而非原始字节。
部分操作会强制要求运行时查询特性（例如
```
contactCustomerNumberAvailabilityCheck
```
在运行时需要
```
customerNumber
```
参数）。
可使用
```
op-show
```
或
```
ops-quirks
```
查看特定操作的运行时特性。

References

参考资料

Command cheat sheet:
```
references/command-cheatsheet.md
```

命令速查表：
```
references/command-cheatsheet.md
```