Documents and Ploybooks

Last updated

Workspace documents

CommandWhat it does
ploy documents list [--limit <n>] [--cursor <cursor>] [--json]List one page of document summaries, 50 by default.
ploy documents get (--id <id> | --path <path>) [--json]Print Markdown content, or the complete response envelope as JSON.
ploy documents set <path> [--title <title>] [--json]Read Markdown from stdin and create or update the exact path.
Work with documents
ploy documents list
ploy documents get --path /briefs/launch.md
ploy documents get --id <document-id> --json
ploy documents set /briefs/launch.md --title "Launch brief" < launch.md
Page through documents
ploy documents list --limit 100 --json
ploy documents list --limit 100 --cursor <cursor> --json

--limit accepts 1 to 100. When more documents exist, the response includes nextCursor. Pass it to --cursor to read the next page. Without --json, the CLI prints the next cursor on standard error. The list is not sorted by most recent update. Documents that are added or removed while you page can shift between pages. To read a document you know, use ploy documents get --path <path>.

Document paths start with /, contain no blank segments, and end in a segment of at most 200 characters. Titles are non-blank and at most 200 characters. Content is limited to 1,000,000 characters.

Document object
{
  "id": "<document-id>",
  "title": "Launch brief",
  "path": "/briefs/launch.md",
  "content": "# Launch brief\n",
  "tags": [],
  "createdBy": "<user-id>",
  "createdAt": "<ISO-8601 timestamp>",
  "updatedAt": "<ISO-8601 timestamp>"
}

List responses omit content and include limit, hasMore, and nextCursor when another page exists. Set responses contain document and operation: "created" | "updated". Document commands do not support --dry-run.

Read Ploybooks

Ploybook commands require an effective workspace and workspace membership. They print pretty-formatted JSON.

CommandUse it for
ploy ploybooks listReturn { "ploybooks": [...] }.
ploy ploybook get <id>Read a line slice of Markdown content.
ploy ploybook read <id>Alias of get.
ploy ploybook outline <id>Return a Markdown heading tree with stable section paths.
ploy ploybook read-section <id> <path>Read one section by a path emitted from outline.
Read Ploybooks
ploy ploybooks list
ploy ploybook outline <ploybook-id>
ploy ploybook read-section <ploybook-id> phase-1/setup
ploy ploybook get <ploybook-id> --offset 0 --limit 500

offset defaults to 0 and must be non-negative. limit defaults to 500 and accepts 1 through 500.

Create and update Ploybooks

Create or update a Ploybook
ploy ploybook create \
  --title "Weekly traffic digest" \
  --content-file ./weekly-traffic.md \
  --description "Summarize traffic and post the result" \
  --tag analytics \
  --tag reporting

ploy ploybook update <ploybook-id> --content-file - < weekly-traffic.md
ploy ploybook update <ploybook-id> --clear-tags
  • Title: 1–200 characters.
  • Description: at most 1,000 characters.
  • Tags: at most 20; each at most 50 characters.
  • Content: non-empty UTF-8; at most 500,000 characters.
  • --tag may be repeated. --clear-tags conflicts with --tag.

Apply exact edits

ploy ploybook edit applies 1–10 exact text replacements from inline JSON or a file.

edits.json
[
  {
    "old_string": "exact text to replace",
    "new_string": "replacement text"
  }
]
Edit a Ploybook
ploy ploybook edit <ploybook-id> --edits-file edits.json
ploy ploybook edit <ploybook-id> --edits '[{"old_string":"old","new_string":"new"}]'

Delete a Ploybook

Delete a Ploybook
ploy ploybook delete <ploybook-id>

Create, update, edit, delete, and schedule mutations support global --dry-run. During a dry run, the CLI does not read content or edit files and does not make mutation requests.

Schedules

Manage schedules
ploy ploybook schedule list <ploybook-id>
ploy ploybook schedule create <ploybook-id> --cron "0 9 * * 1-5" --timezone America/New_York
ploy ploybook schedule update <ploybook-id> <schedule-id> --disabled
ploy ploybook schedule delete <ploybook-id> <schedule-id>

Cron uses a valid five-field expression up to 200 characters. Timezone uses a valid IANA identifier up to 100 characters and defaults to UTC. New schedules are enabled unless --disabled is passed.

Keep going