# Docs CLI Workflow > Guides when to use the docs create/edit CLI tools versus direct file editing for InfluxData documentation. Use when deciding whether to scaffold new pages with docs create, open existing pages with docs edit, or edit Markdown files directly. - Skill: `influxdata/docs-cli-workflow` (Agent Skill) - Install (CLI): `npx skillmds@latest add influxdata/docs-cli-workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/influxdata/docs-cli-workflow/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: influxdata (https://skillmd.com/u/influxdata) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/influxdata/docs-cli-workflow --- # docs CLI Workflow Guidance ## Purpose Help recognize when to suggest `docs create` or `docs edit` CLI tools instead of direct file editing. These tools provide scaffolding, context gathering, and education about conventions that direct editing misses. ## When This Skill Applies Check for these trigger keywords in user messages: - "new page", "new doc", "create documentation", "add a page" - "edit this URL", "edit ", "update this page" (with a URL) - "document this feature", "write docs for" - "I have a draft", "from this draft" - Any docs.influxdata.com URL **Skip this skill when:** - User provides an explicit file path (e.g., "fix typo in content/influxdb3/...") - Small fixes (typos, broken links) - User says "just edit it" or similar - Frontmatter-only changes ## Decision: Which Tool to Suggest ### Suggest `docs create` when | Trigger | Why CLI is better | | -------------------------------------- | --------------------------------------------------------- | | Content targets multiple products | CLI scaffolds shared content pattern automatically | | User unsure where page should live | CLI analyzes structure, suggests location | | Draft references existing docs | CLI extracts links, provides context to avoid duplication | | User seems unfamiliar with conventions | CLI prompt includes style guide, shortcode examples | | Complex new feature documentation | CLI gathers product metadata, version info | ### Suggest `docs edit` when | Trigger | Why CLI is better | | -------------------------------------- | ------------------------------------------------------ | | User provides docs.influxdata.com URL | CLI finds source file(s) including shared content | | User doesn't know source file location | CLI maps URL to file path(s) | | Page uses shared content | CLI identifies both frontmatter file AND shared source | ### Edit directly when | Scenario | Why direct is fine | | -------------------------------- | ------------------------------- | | User provides explicit file path | They already know where to edit | | Small typo/link fixes | CLI overhead not worth it | | User says "just edit it" | Explicit preference to skip CLI | | Frontmatter-only changes | No content generation needed | ## How to Suggest When a trigger is detected, present a concise recommendation and wait for confirmation. ### For `docs create` ``` I'd recommend using the docs CLI for this: docs create --products **Why**: [1-2 sentences explaining the specific benefit] Options: 1. **Use CLI** - I'll run the command and guide you through product selection 2. **Edit directly** - Skip the CLI, I'll create/edit files manually Which do you prefer? ``` ### For `docs edit` ``` I can use the docs CLI to find the source files for this page: docs edit **Why**: [1-2 sentences explaining the benefit] Options: 1. **Use CLI** - I'll find and list the relevant files (non-blocking) 2. **I know the file** - Tell me the path and I'll edit directly Which do you prefer? ``` ### Key principles - Show the actual command (educational) - Explain *why* for this specific case - Always offer the direct alternative - Keep it brief (4-6 lines max) - **Wait for user confirmation before running** ## Edge Cases | Situation | Behavior | | ----------------------------------- | -------------------------------------------------------------------------------------------------------- | | Already in a `docs create` workflow | Don't re-suggest | | URL points to non-existent page | Suggest creating a draft, then run `docs create --url --from-draft ` instead of `docs edit` | | User provides both URL and draft | Suggest `docs create --url --from-draft ` | | User declines CLI twice in session | Stop suggesting, respect preference | ## After User Confirms Run the appropriate command and let the CLI handle the rest. No additional guidance needed—the CLI manages product selection, file generation, and context gathering. ## CLI Reference The unified `docs` CLI includes all documentation tooling commands. **Product targeting:** `--products` accepts both product keys (`influxdb3_core`) and content paths (`/influxdb3/core`). ```bash # CREATE: Create new documentation from a draft docs create --products docs create --products /influxdb3/core,/influxdb3/enterprise docs create --products influxdb3_core --open # Non-blocking docs create --url --from-draft # Create at URL # EDIT: Find and edit existing documentation docs edit # Non-blocking, agent-friendly docs edit --list # List files without opening docs edit --wait # Block until editor closes docs edit --editor nano # Use specific editor # PLACEHOLDERS: Add placeholder syntax to code blocks docs placeholders # Add { placeholders="PATTERN" } syntax docs placeholders --dry # Preview changes without writing # AUDIT: Audit documentation coverage docs audit --products influxdb3_core # Default version: main docs audit --products /influxdb3/core --version v3.3.0 # Specific version docs audit --products influxdb3_core,influxdb3_enterprise docs audit --repos ~/github/influxdata/influxdb # Direct repo path # RELEASE-NOTES: Generate release notes from commits docs release-notes v3.1.0 v3.2.0 --products influxdb3_core docs release-notes v3.1.0 v3.2.0 --products /influxdb3/core,/influxdb3/enterprise docs release-notes v3.1.0 v3.2.0 --repos ~/repos/influxdb # Examples docs edit https://docs.influxdata.com/influxdb3/core/admin/databases/ docs edit /influxdb3/core/admin/databases/ docs placeholders content/influxdb3/core/admin/databases/create.md ``` **Note:** `--products` and `--repos` are mutually exclusive for `audit` and `release-notes`. **Editor Selection** (checked in order): 1. `--editor` flag 2. `DOCS_EDITOR` environment variable 3. `VISUAL` environment variable 4. `EDITOR` environment variable 5. System default **Important for AI Agents**: - Both `docs edit` and `docs create --open` commands are non-blocking by default (launch editor in background and exit immediately) - This prevents agents from hanging while waiting for user editing - Use `--wait` only when you need to block until editing is complete - For `docs create`, omit `--open` to skip editor entirely (files are created and CLI exits) For full CLI documentation, run `docs --help`. ## Related Skills - **hugo-template-dev** - For Hugo template syntax, data access patterns, and runtime testing - **cypress-e2e-testing** - For running and debugging Cypress E2E tests - **ts-component-dev** (agent) - TypeScript component behavior and interactivity