docs: migrate CLI section to v4 consolidated reference

[Ethan-Arrowood]

CLI Section Migration

Summary

Migration of CLI documentation from versioned_docs into new consolidated reference structure at reference_versioned_docs/version-v4/cli/.

Files Created

• reference_versioned_docs/version-v4/cli/overview.md - General CLI overview with installation path, ROOTPATH configuration, process ID file location, system management commands, remote operations, and development mode
• reference_versioned_docs/version-v4/cli/commands.md - Detailed reference for core CLI commands (start, run, dev, restart, stop, status, compact)
• reference_versioned_docs/version-v4/cli/operations-api-commands.md - Complete operations available through CLI with version information for all 72 operations
• reference_versioned_docs/version-v4/cli/authentication.md - Authentication mechanisms for local (Unix domain sockets) and remote operations
• migration-context/link-placeholders/cli-link-placeholders.md - Comprehensive tracking of all TODO links for future cross-section resolution

Key Features

Version Annotations

All CLI operations now include "Available Since" information:

• 51 operations from v4.3.0
• 11 operations from v4.4.0 (6 SSH operations: add_ssh_key, update_ssh_key, delete_ssh_key, list_ssh_keys, set_ssh_known_hosts, get_ssh_known_hosts + 5 certificate operations: create_csr, sign_certificate, list_certificates, add_certificate, remove_certificate)
• 3 data operations from v4.4.9 (insert, update, upsert)
• 3 status operations from v4.6.0 (get_status, set_status, clear_status)
• get_ssh_key from v4.7.2
• get_usage_licenses from v4.7.3

Content Consolidation

Merged content from v4.1 through v4.7 with inline version annotations following Node.js documentation patterns (e.g., "Available since: v4.3.0; expanded in: v4.7.0").

Authentication Documentation

• Unix domain socket authentication for local operations (automatically authenticated as superuser) - corrected from initial misunderstanding about config-based authentication
• Detailed environment variable (CLI_TARGET_USERNAME, CLI_TARGET_PASSWORD) and command parameter methods for remote operations
• Security best practices for credential management including secret manager integration examples

Operations API Commands

• Complete operations table with 72 operations categorized by function (Database, Data, Security, Clustering, Components, Configuration, Authentication, System, Licensing, Jobs, Logging, Maintenance, Status)
• Version information for each operation with no TODO entries remaining
• Command aliases: deploy → deploy_component, package → package_component
• Parameter formatting guidelines (string, array, object, boolean)
• Cross-references to related reference sections via tip callouts (Database, REST, GraphQL, Configuration, Components, Security)

Process Management

• Documented PID file location at <ROOTPATH>/hdb.pid for external process management tools
• Clarified that harper run runs in foreground mode (not background)
• Updated harper dev features: logs to standard streams, single-threaded execution
• Clarified harper restart works with both foreground and background processes

Link Management

• 12 internal CLI section links resolved using relative paths (./overview.md, ./commands.md, etc.)
• ~96 cross-section TODO links documented for future resolution
• All placeholder links tracked in cli-link-placeholders.md with line numbers, context, target, and status

Source Files Used

reference_versioned_docs/version-v4/cli/overview.md

• versioned_docs/version-4.7/deployments/harper-cli.md (primary source)
• versioned_docs/version-4.4/deployments/harper-cli.md (for baseline features)
• release-notes/v4-tucker/4.3.0.md (confirmed CLI expansion in v4.3.0)
• release-notes/v4-tucker/4.2.0.md (confirmed dev mode in v4.2.0)
• release-notes/v4-tucker/4.1.0.md (confirmed foreground mode changes in v4.1.0)

reference_versioned_docs/version-v4/cli/commands.md

• versioned_docs/version-4.7/deployments/harper-cli.md (primary)
• release-notes/v4-tucker/4.2.0.md (dev mode commands)
• release-notes/v4-tucker/4.1.0.md (foreground mode changes)

reference_versioned_docs/version-v4/cli/operations-api-commands.md

• versioned_docs/version-4.7/deployments/harper-cli.md (primary)
• release-notes/v4-tucker/4.3.0.md (confirmed CLI expansion with operations API commands in v4.3.0)
• Harper CLI source code (SUPPORTED_OPS and OP_ALIASES arrays from v4.3.0)
• Multiple release notes for operation version tracking (4.4.0, 4.4.9, 4.6.0, 4.7.2, 4.7.3, 4.7.14)

reference_versioned_docs/version-v4/cli/authentication.md

• versioned_docs/version-4.7/deployments/harper-cli.md (primary)
• versioned_docs/version-4.4/deployments/harper-cli.md (baseline features)

Migration Approach

This migration follows the established patterns:

• Single consolidated v4 reference (no separate v4.1-v4.7 versions)
• Inline version annotations for feature availability
• TODO: prefix for cross-section links pending future migrations
• Comprehensive source attribution in HTML comments
• Learn guide links use /learn paths
• Consistent use of harper command (not harperdb) throughout

Next Steps

Pending link resolutions will be addressed in future section migrations:

• Operations API section (~82 links): 5 overview/operations page links + 72 operation category links + 5 additional references
• Configuration section (5 links)
• Database section (3 links)
• Security section (4 links)
• Logging section (1 link)
• Components section (1 link)
• REST section (1 link)
• GraphQL Querying section (1 link)
• Applications section (1 link)
• Learn Guides (1 external link for deploying applications)

Total Pending Links: ~96

Notes

This is Pilot Section 1 of the v4 documentation migration, chosen for:

• Relatively stable content across versions
• Simple structure (4 files)
• Good test of the entire workflow
• Low risk for validation

The migration successfully:

• ✅ Extracted content from primary sources
• ✅ Added inline source documentation
• ✅ Included version annotations with complete coverage (all 72 operations)
• ✅ Created link placeholders for cross-references
• ✅ Generated comprehensive link placeholder tracker file
• ✅ Updated migration map status
• ✅ Corrected authentication documentation (Unix domain sockets)
• ✅ Added PID file location documentation
• ✅ Clarified command behaviors (foreground/background, dev mode features)
• ✅ Removed harperdb command references (replaced with harper)

[kriszyp]

This might take some clarification; logs doesn't necessary go to the console, the logger.stdStream config option controls whether logs go to stdout/stderr. And stdout/stderr goes to the console if the process is in the "foreground" (that's kind of part of the definition of a foreground process).

[Ethan-Arrowood]

I can work on clarifying this. Its important that we are technically accurate here to not cause any confusion