49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# Step documents (cp-docs-token)
|
|
|
|
This step can read and write planner documents through `python3 -m lib.cp_cli`
|
|
in step-docs mode (PLN-CLI-16). The mode is active because `CP_DOCS_TOKEN_FILE`
|
|
and `CP_DOCS_CA_FILE` are set and the listener URL is in `CP_DOCS_URL`.
|
|
|
|
## Credential
|
|
|
|
- The token is a file at `$CP_DOCS_TOKEN_FILE`. cp-cli reads it on every call.
|
|
- Never print, copy, log or pass the token on a command line.
|
|
- Do not use `~/.cpconfig`; step-docs mode does not read it.
|
|
|
|
## Allowed commands
|
|
|
|
Only these commands work; anything else exits 2 `cp_docs_mode_command_not_allowed`:
|
|
|
|
```
|
|
python3 -m lib.cp_cli planner items documents list <item-uuid>
|
|
python3 -m lib.cp_cli planner items documents get <item-uuid> <name> [--json]
|
|
python3 -m lib.cp_cli planner items documents put <item-uuid> <name> --file <path> (--create-only | --if-match <rev>)
|
|
python3 -m lib.cp_cli planner items documents related [--json]
|
|
```
|
|
|
|
Item arguments are full UUIDs. Do not pass a project id.
|
|
|
|
## Scope
|
|
|
|
- You may write only documents on this step's own item.
|
|
- You may read documents on this step's item, its parent and its siblings.
|
|
- `related` prints `item_uuid`, `parent_uuid`, `sibling_uuids` and `siblings_truncated`.
|
|
|
|
## Writes need a precondition
|
|
|
|
Exactly one of these is required on every `put` (neither or both exits 2):
|
|
|
|
- `--create-only` creates a new document (sends `If-None-Match: *`).
|
|
- `--if-match <rev>` updates an existing one (sends `If-Match`). Take `<rev>`
|
|
from `get --json` (the ETag revision); surrounding quotes are stripped.
|
|
|
|
## Errors
|
|
|
|
- 412 `precondition_failed`: the document changed or already exists. Re-run
|
|
`get --json`, merge your change into the current content, and `put` again
|
|
with the new revision.
|
|
- 428 (precondition missing): add `--create-only` or `--if-match`.
|
|
- 429 `step_docs_write_budget_exhausted` or `step_docs_rate_limited`: stop
|
|
writing; do not retry in a loop.
|
|
- 404 `not_found`, 400 `invalid_document_name`: fix the item uuid or name.
|