# @nexusclawhq/cli

NexusClaw developer CLI for authenticated workspace source, package, and deployment workflows.

```bash
npm install --global @nexusclawhq/cli
nexus --version
nexus org login-web --instance-url https://your-nexusclaw.example --alias dev
```

Remote DX commands resolve one fail-closed target from `--workspace-id`, `--target-org`, the selected environment descriptor, and the authenticated org credential. `defaultOrg` is always an org alias and is never sent as a workspace ID.

Node.js 18 or newer is required. Credentials are encrypted under `~/.nexusclaw` by default; set `NEXUS_CLI_HOME` to use an isolated credential directory in CI.

## Data query field observations

`nexus data query` projects fields from the permission-protected `records`
response. An active exported metadata field is a declaration; it does not
guarantee a value in every returned record. This command does not assess schema
support or field permissions independently of that response.

With `--json`, `data.fieldAvailability` describes only the returned page:

| Property | Meaning |
| --- | --- |
| `source: "returned-records"` | The catalog is derived from actual returned keys, not exported metadata. |
| `schemaSupport: "not-assessed"` | These observations cannot establish whether a field exists, is enabled, or is readable. |
| `observedFields` | Union of keys present in at least one returned row, including keys with `false` or `null` values. |
| `unobservedFields` | Requested fields absent from every returned row; case-insensitive matches count as observed. An empty page cannot infer this list and returns `[]`. |

Legacy `data.availableFields` aliases `observedFields`; legacy
`data.unknownFields` aliases `unobservedFields`. The latter name does **not**
mean an unknown schema field or an unsupported query field. New consumers
should use `fieldAvailability` rather than infer model support from those names.

Unobserved requested fields produce the structured warning
`DATA_QUERY_FIELDS_UNOBSERVED`, while a successful query retains exit code `0`.
Text output states the same observation boundary. No values are filled in:
missing keys remain omitted in JSON, present `false`/`null` values are preserved,
and no metadata default is substituted. Compare declarations and permissions in
the same workspace when further diagnosis is needed. This is a data projection
contract, not a promise of full Salesforce SOQL compatibility.

## AI workforce training & governance (`workforce`)

`nexus workforce *` drives the full digital-employee lifecycle from the CLI without the UI — learning loops, cognition, config writes, eval, ops, orchestration, and observation. See [`docs/workforce-cli.md`](./docs/workforce-cli.md) for the command reference, the step-up (MFA) bootstrap, known non-implemented items (skills / distill-run), and the governance-contract registration gap.


### 视频素材的受控转写替代入口

当前 `knowledge ingest-file` 只解析 PDF/DOCX/TXT。MP4/HEVC 原视频须由素材 owner
保存在受控素材位置；CLI 不改变视频文件白名单，不上传视频、不承诺自动理解画面或生成 SOP。
先通过已有转写工具形成 UTF-8 文本，再由人员核验操作顺序、术语、画面信息及敏感内容。

```sh
nexus workforce knowledge ingest-transcript --target-org development \
  --title '现场操作转写' --video-file ./capture.mp4 \
  --source-url https://your-authorized-asset-host/path/to/original \
  --transcript-file ./reviewed-transcript.txt --reviewed --access-level private --json
nexus workforce knowledge chunk-get --target-org development --ids '<返回的 chunkIds，逗号分隔>' --json
```

使用素材 owner 提供的持久 HTTPS 地址，不放入访问令牌、签名参数或本地文件路径。
入库内容是核验后的转写；返回的 chunk 保留原视频文件名、字节数、SHA-256、来源地址、
转写 SHA-256 和权限。修改视频或转写会产生不同摘要，不覆盖已有版本。
默认知识权限为 `private`；组织内分享须显式指定 `org_subtree` 与 `--org-node-id`。
知识访问权限不会授予原视频访问权；原视频仍由素材 owner 管理授权。
检查 `failedChunks=0` 后再用于知识绑定；SOP/技能发布仍须走现有审核和 release gate。