hana-developer-cli-tool-example command-documentation.instructions.md

CLI Command Documentation Guidelines

When documenting CLI commands for the hana-cli tool, follow this structured format to ensure consistency and completeness.

Preservation Rule (Do Not Strip Existing Content)

When updating an existing documentation file, preserve any additional description or educational content already present.

Only replace or insert content inside the specific section you are updating, and do not delete other paragraphs, lists, or subsections that provide extra context. This is especially important for Description and Educational Context content that may span multiple paragraphs.

Practical guidance:

• Keep all existing descriptive paragraphs unless they directly contradict verified behavior.
• When re-generating sections, update the section body but leave any extra subheadings or explanatory text that belong to the command.
• Never remove sections like “What is …?”, “How is … Used?”, or other narrative blocks unless explicitly asked to delete them.

Critical: Filename vs Command Name

The filename is NOT the command name.

• Filename: Uses kebab-case for organization (e.g., column-stats.md)
• Command Name: Uses camelCase as defined in code (e.g., columnStats)
• Source of Truth: Always the export const command in bin/[commandName].js

Example:

File:    docs/02-commands/analysis-tools/column-stats.md  ← kebab-case
Command: columnStats  ← camelCase (from bin/columnStats.js)
Help:    hana-cli columnStats [schema] [table]

Never assume the command name from the filename. Always verify in the command's source code.

Document Structure

Every command documentation file must include these sections in order:

1. Header Section

# commandName

> Command: `commandName`  
> Category: **Category Name**  
> Status: Production Ready | Early Access | Beta | Experimental

## Description

[Clear, concise description of what the command does]

[Optional: Extended explanation with context, use cases, and background information]