diff --git a/migration-context/link-placeholders/cli-link-placeholders.md b/migration-context/link-placeholders/cli-link-placeholders.md new file mode 100644 index 00000000..60f8485e --- /dev/null +++ b/migration-context/link-placeholders/cli-link-placeholders.md @@ -0,0 +1,282 @@ +# Link Placeholders for CLI Section + +This document tracks all link placeholders in the CLI section that need to be resolved once other sections are migrated. + +## reference_versioned_docs/version-v4/cli/overview.md + +- Line 30: `[CLI Authentication](TODO:reference_versioned_docs/version-v4/cli/authentication.md "CLI authentication details")` + - Context: Linking to CLI authentication details + - Target: CLI authentication page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 45: `[CLI Commands](TODO:reference_versioned_docs/version-v4/cli/commands.md "Detailed CLI command reference")` + - Context: Linking to detailed CLI commands + - Target: CLI commands page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 60: `[Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API overview")` + - Context: Linking to Operations API overview + - Target: Operations API section overview page + - **Status**: PENDING (will be created in Operations API section migration) + +- Line 100: `[Operations API Commands](TODO:reference_versioned_docs/version-v4/cli/operations-api-commands.md "Operations API CLI commands reference")` + - Context: Linking to operations API commands via CLI + - Target: Operations API commands page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 126: `[Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md "Configuration overview")` + - Context: Linking to configuration options + - Target: Configuration section overview + - **Status**: PENDING (will be created in Configuration section migration) + +- Line 144: `[Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API")` + - Context: Linking to full operations API reference + - Target: Operations API section overview page + - **Status**: PENDING (will be created in Operations API section migration) + +## reference_versioned_docs/version-v4/cli/commands.md + +- Line 9: `[Operations API Commands](TODO:reference_versioned_docs/version-v4/cli/operations-api-commands.md "Operations API CLI commands")` + - Context: Referring users to operations API commands documentation + - Target: Operations API commands page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 52: `[Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md "Configuration overview")` + - Context: Linking to configuration parameters + - Target: Configuration section overview + - **Status**: PENDING (will be created in Configuration section migration) + +- Line 125: `[Database Compaction](TODO:reference_versioned_docs/version-v4/database/compaction.md "Database compaction reference")` + - Context: Linking to database compaction details + - Target: Database section compaction page + - **Status**: PENDING (will be created in Database section migration) + +- Line 146: `[CLI Overview - Remote Operations](TODO:reference_versioned_docs/version-v4/cli/overview.md#remote-operations "Remote operations documentation")` + - Context: Linking to remote operations section in overview + - Target: CLI overview page, remote operations section + - **Status**: RESOLVED (file created in this migration) + +- Line 151: `[CLI Overview](TODO:reference_versioned_docs/version-v4/cli/overview.md "CLI overview")` + - Context: Linking back to CLI overview + - Target: CLI overview page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 152: `[Operations API Commands](TODO:reference_versioned_docs/version-v4/cli/operations-api-commands.md "Operations API commands")` + - Context: Linking to operations API commands + - Target: Operations API commands page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 153: `[CLI Authentication](TODO:reference_versioned_docs/version-v4/cli/authentication.md "CLI authentication")` + - Context: Linking to authentication mechanisms + - Target: CLI authentication page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 154: `[Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md "Configuration")` + - Context: Linking to configuration parameters + - Target: Configuration section overview + - **Status**: PENDING (will be created in Configuration section migration) + +- Line 155: `[Database Compaction](TODO:reference_versioned_docs/version-v4/database/compaction.md "Compaction")` + - Context: Linking to compaction details + - Target: Database section compaction page + - **Status**: PENDING (will be created in Database section migration) + +## reference_versioned_docs/version-v4/cli/operations-api-commands.md + +- Line 12: `[Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API overview")` + - Context: Introduction paragraph + - Target: Operations API section overview page + - **Status**: PENDING (will be created in Operations API section migration) + +- Lines 38-109: 72 operations table entries with category links + - `[Database](TODO:../operations-api/database.md)` (9 operations) + - `[Data](TODO:../operations-api/data.md)` (9 operations) + - `[Security](TODO:../operations-api/security.md)` (17 operations) + - `[Clustering](TODO:../operations-api/clustering.md)` (4 operations) + - `[Components](TODO:../operations-api/components.md)` (9 operations) + - `[Configuration](TODO:../operations-api/configuration.md)` (2 operations) + - `[Authentication](TODO:../operations-api/authentication.md)` (2 operations) + - `[System](TODO:../operations-api/system.md)` (3 operations) + - `[Licensing](TODO:../operations-api/licensing.md)` (4 operations) + - `[Jobs](TODO:../operations-api/jobs.md)` (2 operations) + - `[Logging](TODO:../operations-api/logging.md)` (4 operations) + - `[Maintenance](TODO:../operations-api/maintenance.md)` (2 operations) + - `[Status](TODO:../operations-api/status.md)` (3 operations) + - Context: Operations table linking to operation category documentation + - Target: Operations API section category pages + - **Status**: PENDING (will be created in Operations API section migration) + +- Line 118: `[Operations API documentation](TODO:reference_versioned_docs/version-v4/operations-api/operations.md "Complete operations list")` + - Context: After Command Aliases section + - Target: Operations API section operations page + - **Status**: PENDING (will be created in Operations API section migration) + +- Line 150: `[Database Reference](TODO:reference_versioned_docs/version-v4/database/overview.md "Database reference documentation")` + - Context: Tip callout in Database Operations examples + - Target: Database section overview + - **Status**: PENDING (will be created in Database section migration) + +- Line 168: `[REST Reference](TODO:reference_versioned_docs/version-v4/rest/overview.md "REST API reference")` + - Context: Tip callout in Data Operations examples + - Target: REST section overview + - **Status**: PENDING (will be created in REST section migration) + +- Line 168: `[GraphQL Querying](TODO:reference_versioned_docs/version-v4/graphql-querying/overview.md "GraphQL querying reference")` + - Context: Tip callout in Data Operations examples + - Target: GraphQL Querying section overview + - **Status**: PENDING (will be created in GraphQL Querying section migration) + +- Line 186: `[Configuration Reference](TODO:reference_versioned_docs/version-v4/configuration/overview.md "Configuration reference")` + - Context: Tip callout in Configuration Operations examples + - Target: Configuration section overview + - **Status**: PENDING (will be created in Configuration section migration) + +- Line 204: `[Components Reference](TODO:reference_versioned_docs/version-v4/components/overview.md "Components reference")` + - Context: Tip callout in Component Operations examples + - Target: Components section overview + - **Status**: PENDING (will be created in Components section migration) + +- Line 222: `[Security Reference](TODO:reference_versioned_docs/version-v4/security/overview.md "Security reference")` + - Context: Tip callout in User and Role Operations examples + - Target: Security section overview + - **Status**: PENDING (will be created in Security section migration) + +- Line 227: `[CLI Overview - Remote Operations](./overview.md#remote-operations)` + - Context: Remote Operations section + - Target: CLI overview page, remote operations anchor + - **Status**: RESOLVED (file created in this migration) + +- Line 245: `[Applications](TODO:reference_versioned_docs/version-v4/applications/overview.md "Applications reference")` + - Context: Remote Component Deployment section + - Target: Applications section (or Components section) + - **Status**: PENDING (will be created in future section migration) + +- Line 246: `[Deploying Harper Applications](TODO:learn_link "Deploying applications guide")` + - Context: Remote Component Deployment section + - Target: Learn guide on deploying applications + - **Status**: PENDING (external learn link) + +- Line 372: `[Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API")` + - Context: Limitations section + - Target: Operations API section overview page + - **Status**: PENDING (will be created in Operations API section migration) + +- Line 376: `[CLI Overview](./overview.md)` + - Context: See Also section + - Target: CLI overview page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 377: `[CLI Commands](./commands.md)` + - Context: See Also section + - Target: CLI commands page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 378: `[Operations API Overview](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API overview")` + - Context: See Also section + - Target: Operations API section overview page + - **Status**: PENDING (will be created in Operations API section migration) + +- Line 379: `[Operations API Reference](TODO:reference_versioned_docs/version-v4/operations-api/operations.md "Operations reference")` + - Context: See Also section + - Target: Operations API section operations page + - **Status**: PENDING (will be created in Operations API section migration) + +- Line 380: `[CLI Authentication](./authentication.md)` + - Context: See Also section + - Target: CLI authentication page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +## reference_versioned_docs/version-v4/cli/authentication.md + +- Line 196: `[Users and Roles](TODO:reference_versioned_docs/version-v4/security/users-and-roles.md "Users and roles documentation")` + - Context: Linking to user management and permissions (Security Best Practices section) + - Target: Security section users and roles page + - **Status**: PENDING (will be created in Security section migration) + +- Line 204: `[Logging](TODO:reference_versioned_docs/version-v4/logging/overview.md "Logging documentation")` + - Context: Linking to audit logging information (Security Best Practices section) + - Target: Logging section overview + - **Status**: PENDING (will be created in Logging section migration) + +- Line 256: `[CLI Overview](./overview.md)` + - Context: See Also section + - Target: CLI overview page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 257: `[CLI Commands](./commands.md)` + - Context: See Also section + - Target: CLI commands page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 258: `[Operations API Commands](./operations-api-commands.md)` + - Context: See Also section + - Target: Operations API commands page (within CLI section) + - **Status**: RESOLVED (file created in this migration) + +- Line 259: `[Security Overview](TODO:reference_versioned_docs/version-v4/security/overview.md "Security overview")` + - Context: See Also section + - Target: Security section overview page + - **Status**: PENDING (will be created in Security section migration) + +- Line 260: `[Users and Roles](TODO:reference_versioned_docs/version-v4/security/users-and-roles.md "Users and roles")` + - Context: See Also section + - Target: Security section users and roles page + - **Status**: PENDING (will be created in Security section migration) + +## Summary + +### Resolved Links (Within CLI Section) +- 12 links to pages within the CLI section (all resolved in this migration) +- All internal CLI section links now use relative paths (e.g., `./overview.md`) + +### Pending Links (Cross-Section References) +These will be resolved in future section migrations: + +**Operations API Section** (~82 links): +- `reference_versioned_docs/version-v4/operations-api/overview.md` (5 occurrences) +- `reference_versioned_docs/version-v4/operations-api/operations.md` (2 occurrences) +- Operations table category pages (72 links): + - `../operations-api/database.md` + - `../operations-api/data.md` + - `../operations-api/security.md` + - `../operations-api/clustering.md` + - `../operations-api/components.md` + - `../operations-api/configuration.md` + - `../operations-api/authentication.md` + - `../operations-api/system.md` + - `../operations-api/licensing.md` + - `../operations-api/jobs.md` + - `../operations-api/logging.md` + - `../operations-api/maintenance.md` + - `../operations-api/status.md` + +**Configuration Section** (5 links): +- `reference_versioned_docs/version-v4/configuration/overview.md` + +**Database Section** (3 links): +- `reference_versioned_docs/version-v4/database/compaction.md` (2 occurrences) +- `reference_versioned_docs/version-v4/database/overview.md` (1 occurrence) + +**Security Section** (4 links): +- `reference_versioned_docs/version-v4/security/overview.md` (2 occurrences) +- `reference_versioned_docs/version-v4/security/users-and-roles.md` (2 occurrences) + +**Logging Section** (1 link): +- `reference_versioned_docs/version-v4/logging/overview.md` + +**Components Section** (1 link): +- `reference_versioned_docs/version-v4/components/overview.md` + +**REST Section** (1 link): +- `reference_versioned_docs/version-v4/rest/overview.md` + +**GraphQL Querying Section** (1 link): +- `reference_versioned_docs/version-v4/graphql-querying/overview.md` + +**Applications Section** (1 link): +- `reference_versioned_docs/version-v4/applications/overview.md` + +**Learn Guides** (1 link): +- Deploying Harper Applications guide (external learn link) + +**Total Pending Links**: ~96 diff --git a/reference_versioned_docs/version-v4/cli/authentication.md b/reference_versioned_docs/version-v4/cli/authentication.md new file mode 100644 index 00000000..1ff6f327 --- /dev/null +++ b/reference_versioned_docs/version-v4/cli/authentication.md @@ -0,0 +1,231 @@ +--- +title: CLI Authentication +--- + + + + +# CLI Authentication + +The Harper CLI handles authentication differently for local and remote operations. + +## Local Operations + +Available since: v4.1.0 + +For local operations (operations executed on the same machine where Harper is installed), the CLI communicates with Harper via Unix domain sockets instead of HTTP. Domain socket requests are automatically authenticated as the superuser, so no additional authentication parameters are required. + +**Example**: + +```bash +# No authentication needed for local operations +harper describe_database database=dev +harper get_components +harper set_configuration logging_level=info +``` + +When no `target` parameter is specified, the CLI defaults to using the local domain socket connection, providing secure, authenticated access to the local Harper instance. + +## Remote Operations + +Available since: v4.1.0; expanded in: v4.3.0 + +For remote operations (operations executed on a remote Harper instance via the `target` parameter), you must provide authentication credentials. + +### Authentication Methods + +#### Method 1: Environment Variables (Recommended) + +Set the following environment variables to avoid exposing credentials in command history: + +```bash +export CLI_TARGET_USERNAME=HDB_ADMIN +export CLI_TARGET_PASSWORD=password +``` + +Then execute remote operations without including credentials in the command: + +```bash +harper describe_database database=dev target=https://server.com:9925 +harper get_components target=https://remote-instance.example.com:9925 +``` + +**Benefits**: +- Credentials not visible in command history +- More secure for scripting +- Can be set once per session +- Supported by most CI/CD systems + +**Example Script**: + +```bash +#!/bin/bash + +# Set credentials from secure environment +export CLI_TARGET_USERNAME=HDB_ADMIN +export CLI_TARGET_PASSWORD=$SECURE_PASSWORD # from secret manager + +# Execute operations +harper deploy target=https://prod-server.com:9925 replicated=true +harper restart target=https://prod-server.com:9925 replicated=true +``` + +#### Method 2: Command Parameters + +Provide credentials directly as command parameters: + +```bash +harper describe_database \ + database=dev \ + target=https://server.com:9925 \ + username=HDB_ADMIN \ + password=password +``` + +**Parameters**: +- `username=` - Harper admin username +- `password=` - Harper admin password + +**Cautions**: +- Credentials visible in command history +- Less secure for production environments +- Exposed in process listings +- Not recommended for scripts + +### Target Parameter + +The `target` parameter specifies the full HTTP/HTTPS URL of the remote Harper instance: + +**Format**: `target=://:` + +**Examples**: + +```bash +# HTTPS on default operations API port +target=https://server.example.com:9925 + +# HTTP (not recommended for production) +target=http://localhost:9925 + +# Custom port +target=https://server.example.com:8080 +``` + +## Security Best Practices + +### 1. Use Environment Variables + +Always use environment variables for credentials in scripts and automation: + +```bash +export CLI_TARGET_USERNAME=HDB_ADMIN +export CLI_TARGET_PASSWORD=$SECURE_PASSWORD +``` + +### 2. Use HTTPS + +Always use HTTPS for remote operations to encrypt credentials in transit: + +```bash +# Good +target=https://server.com:9925 + +# Bad - credentials sent in plain text +target=http://server.com:9925 +``` + +### 3. Manage Secrets Securely + +Store credentials in secure secret management systems: + +- Environment variables from secret managers (AWS Secrets Manager, HashiCorp Vault, etc.) +- CI/CD secret storage (GitHub Secrets, GitLab CI Variables, etc.) +- Operating system credential stores + +**Example with AWS Secrets Manager**: + +```bash +#!/bin/bash + +# Retrieve credentials from AWS Secrets Manager +export CLI_TARGET_USERNAME=$(aws secretsmanager get-secret-value \ + --secret-id harper-admin-user \ + --query SecretString \ + --output text) + +export CLI_TARGET_PASSWORD=$(aws secretsmanager get-secret-value \ + --secret-id harper-admin-password \ + --query SecretString \ + --output text) + +# Execute operations +harper deploy target=https://prod.example.com:9925 +``` + +### 4. Use Least Privilege + +Create dedicated users with minimal required permissions for CLI operations instead of using the main admin account. See [Users and Roles](TODO:reference_versioned_docs/version-v4/security/users-and-roles.md "Users and roles documentation") for more information. + +### 5. Rotate Credentials + +Regularly rotate credentials, especially for automated systems and CI/CD pipelines. + +### 6. Audit Access + +Monitor and audit CLI operations, especially for production environments. See [Logging](TODO:reference_versioned_docs/version-v4/logging/overview.md "Logging documentation") for more information on logging. + +## Troubleshooting + +### Authentication Failures + +If you receive authentication errors: + +1. **Verify credentials are correct**: + - Check username and password + - Ensure no extra whitespace + +2. **Verify the target URL**: + - Ensure the URL is correct and reachable + - Check the port number + - Verify HTTPS/HTTP protocol + +3. **Check network connectivity**: + ```bash + curl https://server.com:9925 + ``` + +4. **Verify user permissions**: + - Ensure the user has permission to execute the operation + - Check user roles and permissions + +### Environment Variable Issues + +If environment variables aren't working: + +1. **Verify variables are set**: + ```bash + echo $CLI_TARGET_USERNAME + echo $CLI_TARGET_PASSWORD + ``` + +2. **Export variables**: + Ensure you used `export`, not just assignment: + ```bash + # Wrong - variable only available in current shell + CLI_TARGET_USERNAME=admin + + # Correct - variable available to child processes + export CLI_TARGET_USERNAME=admin + ``` + +3. **Check variable scope**: + - Variables must be exported before running commands + - Variables set in one terminal don't affect other terminals + +## See Also + +- [CLI Overview](./overview.md) - General CLI information +- [CLI Commands](./commands.md) - Core CLI commands +- [Operations API Commands](./operations-api-commands.md) - Operations available through CLI +- [Security Overview](TODO:reference_versioned_docs/version-v4/security/overview.md "Security overview") - Harper security features +- [Users and Roles](TODO:reference_versioned_docs/version-v4/security/users-and-roles.md "Users and roles") - User management diff --git a/reference_versioned_docs/version-v4/cli/commands.md b/reference_versioned_docs/version-v4/cli/commands.md new file mode 100644 index 00000000..5e4681f1 --- /dev/null +++ b/reference_versioned_docs/version-v4/cli/commands.md @@ -0,0 +1,263 @@ +--- +title: CLI Commands +--- + + + + + + +# CLI Commands + +This page documents the core Harper CLI commands for managing Harper instances. For Operations API commands available through the CLI, see [Operations API Commands](./operations-api-commands.md). + +## Process Management Commands + +### `harper` + +Added in: v4.1.0 + +Run Harper in the foreground as a standard process. This is the recommended way to run Harper. + +```bash +harper +``` + +When you run `harper`: + +- If Harper is not installed, it will guide you through the installation process +- Once installed, it runs Harper in the foreground as a standard process, compatible with systemd, Docker, and other process management tools +- Logs output directly to the console for easy monitoring + +**First-Time Installation**: + +If Harper is not installed, you can provide configuration parameters via environment variables or command line arguments: + +**Using Environment Variables**: + +```bash +# Minimum required parameters for no additional CLI prompts +export TC_AGREEMENT=yes +export HDB_ADMIN_USERNAME=HDB_ADMIN +export HDB_ADMIN_PASSWORD=password +export ROOTPATH=/tmp/hdb/ +export OPERATIONSAPI_NETWORK_PORT=9925 +harper +``` + +**Using Command Line Arguments**: + +```bash +# Minimum required parameters for no additional CLI prompts +harper \ + --TC_AGREEMENT yes \ + --HDB_ADMIN_USERNAME HDB_ADMIN \ + --HDB_ADMIN_PASSWORD password \ + --ROOTPATH /tmp/hdb/ \ + --OPERATIONSAPI_NETWORK_PORT 9925 +``` + +**Note**: When used in conjunction, command line arguments override environment variables. See [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md "Configuration overview") for a full list of configuration parameters. + +:::info +For more information on installation, see [Getting Started / Install and Connect Harper](/learn/getting-started/install-and-connect-harper). +::: + +### `harper run` + +Added in: v4.2.0 (confirmed via release notes) + +Run a Harper application from any location as a foreground, standard process (similar to `harper`). + +```bash +harper run /path/to/app +``` + +This command runs Harper with the specified application directory without automatic reloading or dev-specific features. + +### `harper dev` + +Added in: v4.2.0 (confirmed via release notes) + +Run Harper in development mode from a specified directory with automatic reloading. Recommended for local application development. Operates similar to `harper` and `harper run`. + +```bash +harper dev /path/to/app +``` + +**Features**: +- Pushes logs to standard streams automatically +- Uses a single thread for simpler debugging +- Auto-restart on file changes + +### `harper restart` + +Available since: v4.1.0 + +Restart a running Harper instance regardless if its a foreground (`harper`, `harper run`, or `harper dev`) or background (`harper start`) process. + +```bash +harper restart +``` + +### `harper start` + +Available since: v4.1.0 + +Start Harper in background (daemon mode). + +```bash +harper start +``` + +After installation, this command launches Harper as a background process. Remember that the Harper PID is available in a `hdb.pid` file within the installation directory. + +### `harper stop` + +Available since: v4.1.0 + +Stop a running Harper instance. + +```bash +harper stop +``` + +## Installation Commands + +### `harper install` + +Available since: v4.1.0 + +Install Harper with interactive prompts or automated configuration. + +```bash +harper install +``` + +The `harper install` command operates exactly like the [`harper`](#harper) command, but exits as soon as the installation completes. See the [`harper`](#harper) command documentation above for details on providing configuration parameters via environment variables or command line arguments. + +**Note**: We recommend using `harper` instead of `harper install` as it provides a consistent workflow for both installation and running Harper. + +## Information Commands + +### `harper version` + +Available since: v4.1.0 + +Display the installed Harper version. + +```bash +harper version +``` + +**Example Output**: +``` +4.7.0 +``` + +### `harper status` + +Available since: v4.1.0 + +Display the status of Harper and clustering. + +```bash +harper status +``` + +Shows: +- Harper process status +- Clustering hub and leaf processes +- Clustering network status +- Replication statuses + +### `harper help` + +Available since: v4.1.0 + +Display all available Harper CLI commands with brief descriptions. + +```bash +harper help +``` + +## Maintenance Commands + +### `harper renew-certs` + +Available since: v4.1.0 + +Renew Harper-generated self-signed certificates. + +```bash +harper renew-certs +``` + +This command regenerates the self-signed SSL/TLS certificates used by Harper. + +### `harper copy-db` + +Available since: v4.1.0 + +Copy a Harper database with compaction to eliminate free-space and fragmentation. + +```bash +harper copy-db +``` + +**Parameters**: +- `` - Name of the source database +- `` - Full path to the target database file + +**Example**: + +```bash +harper copy-db data /home/user/hdb/database/copy.mdb +``` + +This copies the default `data` database to a new location with compaction applied. + +**Use Cases**: +- Database optimization +- Eliminating fragmentation +- Creating compacted backups +- Reclaiming free space + +See also: [Database Compaction](TODO:reference_versioned_docs/version-v4/database/compaction.md "Database compaction reference") for more information. + +## Backups + +Available since: v4.1.0 + +Harper uses a transactional commit process that ensures data on disk is always transactionally consistent with storage. This means Harper maintains database integrity in the event of a crash and allows you to use standard volume snapshot tools to make backups. + +**Backup Process**: + +Database files are stored in the `hdb/database` directory. As long as the snapshot is an atomic snapshot of these database files, the data can be copied/moved back into the database directory to restore a previous backup (with Harper shut down), and database integrity will be preserved. + +**Important Notes**: + +- **Atomic Snapshots**: Use volume snapshot tools that create atomic snapshots +- **Not Safe**: Simply copying an in-use database file using `cp` is **not reliable** + - Progressive reads occur at different points in time + - Results in an unreliable copy that likely won't be usable +- **Safe Copying**: Standard file copying is only reliable for database files that are **not in use** + +**Recommended Backup Tools**: +- LVM snapshots +- ZFS snapshots +- BTRFS snapshots +- Cloud provider volume snapshots (AWS EBS, Azure Disk, GCP Persistent Disk) +- Enterprise backup solutions with snapshot capabilities + +## Remote Operations + +The CLI supports executing commands on remote Harper instances. For details, see [CLI Overview - Remote Operations](./overview.md#remote-operations). + +## See Also + +- [CLI Overview](./overview.md) - General CLI information +- [Operations API Commands](./operations-api-commands.md) - Operations available through CLI +- [CLI Authentication](./authentication.md) - Authentication mechanisms +- [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md "Configuration") - Configuration parameters for installation +- [Database Compaction](TODO:reference_versioned_docs/version-v4/database/compaction.md "Compaction") - More on database compaction diff --git a/reference_versioned_docs/version-v4/cli/operations-api-commands.md b/reference_versioned_docs/version-v4/cli/operations-api-commands.md new file mode 100644 index 00000000..faf217d2 --- /dev/null +++ b/reference_versioned_docs/version-v4/cli/operations-api-commands.md @@ -0,0 +1,376 @@ +--- +title: Operations API Commands +--- + + + + +# Operations API Commands + +Added in: v4.3.0 (confirmed via release notes) + +The Harper CLI supports executing operations from the [Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API overview") directly from the command line. This enables powerful automation and scripting capabilities. + +## General Syntax + +```bash +harper = +``` + +**Output Format**: +- Default: YAML +- JSON: Pass `json=true` as a parameter + +## Supported Operations + + + +The following operations are available through the CLI. Operations that require complex nested parameters or object structures are not supported via CLI and must be executed through the HTTP API. + +### Complete Operations List + +:::note +This is just a brief overview of all operations available as CLI commands. Review the respective operation documentation for more information on available arguments and expected behavior. Keep in mind that all operations options are converted to CLI arguments in the same way (using `snake_case`). +::: + +| Operation | Description | Category | Available Since | +|-----------|-------------|----------|-----------------| +| `describe_table` | Describe table structure and metadata | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `describe_all` | Describe all databases and tables | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `describe_database` | Describe database structure | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `create_database` | Create a new database | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `drop_database` | Delete a database | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `create_table` | Create a new table | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `drop_table` | Delete a table | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `create_attribute` | Create a table attribute | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `drop_attribute` | Delete a table attribute | [Database](TODO:../operations-api/database.md) | v4.3.0 | +| `search_by_id` | Search records by ID | [Data](TODO:../operations-api/data.md) | v4.3.0 | +| `search_by_value` | Search records by attribute value | [Data](TODO:../operations-api/data.md) | v4.3.0 | +| `insert` | Insert new records | [Data](TODO:../operations-api/data.md) | v4.4.9 | +| `update` | Update existing records | [Data](TODO:../operations-api/data.md) | v4.4.9 | +| `upsert` | Insert or update records | [Data](TODO:../operations-api/data.md) | v4.4.9 | +| `delete` | Delete records | [Data](TODO:../operations-api/data.md) | v4.3.0 | +| `sql` | Execute SQL queries | [Data](TODO:../operations-api/data.md) | v4.3.0 | +| `csv_file_load` | Load data from CSV file | [Data](TODO:../operations-api/data.md) | v4.3.0 | +| `csv_url_load` | Load data from CSV URL | [Data](TODO:../operations-api/data.md) | v4.3.0 | +| `list_users` | List all users | [Security](TODO:../operations-api/security.md) | v4.3.0 | +| `add_user` | Create a new user | [Security](TODO:../operations-api/security.md) | v4.3.0 | +| `alter_user` | Modify user properties | [Security](TODO:../operations-api/security.md) | v4.3.0 | +| `drop_user` | Delete a user | [Security](TODO:../operations-api/security.md) | v4.3.0 | +| `list_roles` | List all roles | [Security](TODO:../operations-api/security.md) | v4.3.0 | +| `drop_role` | Delete a role | [Security](TODO:../operations-api/security.md) | v4.3.0 | +| `create_csr` | Create certificate signing request | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `sign_certificate` | Sign a certificate | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `list_certificates` | List SSL/TLS certificates | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `add_certificate` | Add SSL/TLS certificate | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `remove_certificate` | Remove SSL/TLS certificate | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `add_ssh_key` | Add SSH key | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `get_ssh_key` | Get SSH key | [Security](TODO:../operations-api/security.md) | v4.7.2 | +| `update_ssh_key` | Update SSH key | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `delete_ssh_key` | Delete SSH key | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `list_ssh_keys` | List all SSH keys | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `set_ssh_known_hosts` | Set SSH known hosts | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `get_ssh_known_hosts` | Get SSH known hosts | [Security](TODO:../operations-api/security.md) | v4.4.0 | +| `cluster_get_routes` | Get cluster routing information | [Clustering](TODO:../operations-api/clustering.md) | v4.3.0 | +| `cluster_network` | Get cluster network status | [Clustering](TODO:../operations-api/clustering.md) | v4.3.0 | +| `cluster_status` | Get cluster status | [Clustering](TODO:../operations-api/clustering.md) | v4.3.0 | +| `remove_node` | Remove node from cluster | [Clustering](TODO:../operations-api/clustering.md) | v4.3.0 | +| `add_component` | Add a component | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `deploy_component` | Deploy a component | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `deploy` (alias) | Alias for `deploy_component` | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `package_component` | Package a component | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `package` (alias) | Alias for `package_component` | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `drop_component` | Remove a component | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `get_components` | List all components | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `get_component_file` | Get component file contents | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `set_component_file` | Set component file contents | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `install_node_modules` | Install Node.js dependencies | [Components](TODO:../operations-api/components.md) | v4.3.0 | +| `set_configuration` | Update configuration settings | [Configuration](TODO:../operations-api/configuration.md) | v4.3.0 | +| `get_configuration` | Get current configuration | [Configuration](TODO:../operations-api/configuration.md) | v4.3.0 | +| `create_authentication_tokens` | Create authentication tokens | [Authentication](TODO:../operations-api/authentication.md) | v4.3.0 | +| `refresh_operation_token` | Refresh operation token | [Authentication](TODO:../operations-api/authentication.md) | v4.3.0 | +| `restart_service` | Restart Harper service | [System](TODO:../operations-api/system.md) | v4.3.0 | +| `restart` | Restart Harper instance | [System](TODO:../operations-api/system.md) | v4.3.0 | +| `system_information` | Get system information | [System](TODO:../operations-api/system.md) | v4.3.0 | +| `registration_info` | Get registration information | [Licensing](TODO:../operations-api/licensing.md) | v4.3.0 | +| `get_fingerprint` | Get instance fingerprint | [Licensing](TODO:../operations-api/licensing.md) | v4.3.0 | +| `set_license` | Set license key | [Licensing](TODO:../operations-api/licensing.md) | v4.3.0 | +| `get_usage_licenses` | Get usage and license info | [Licensing](TODO:../operations-api/licensing.md) | v4.7.3 | +| `get_job` | Get job status | [Jobs](TODO:../operations-api/jobs.md) | v4.3.0 | +| `search_jobs_by_start_date` | Search jobs by start date | [Jobs](TODO:../operations-api/jobs.md) | v4.3.0 | +| `read_log` | Read application logs | [Logging](TODO:../operations-api/logging.md) | v4.3.0 | +| `read_transaction_log` | Read transaction logs | [Logging](TODO:../operations-api/logging.md) | v4.3.0 | +| `read_audit_log` | Read audit logs | [Logging](TODO:../operations-api/logging.md) | v4.3.0 | +| `delete_transaction_logs_before` | Delete old transaction logs | [Logging](TODO:../operations-api/logging.md) | v4.3.0 | +| `purge_stream` | Purge streaming data | [Maintenance](TODO:../operations-api/maintenance.md) | v4.3.0 | +| `delete_records_before` | Delete old records | [Maintenance](TODO:../operations-api/maintenance.md) | v4.3.0 | +| `get_status` | Get custom status information | [Status](TODO:../operations-api/status.md) | v4.6.0 | +| `set_status` | Set custom status information | [Status](TODO:../operations-api/status.md) | v4.6.0 | +| `clear_status` | Clear custom status information | [Status](TODO:../operations-api/status.md) | v4.6.0 | + +### Command Aliases + +The following aliases are available for convenience: + +- `deploy` → `deploy_component` +- `package` → `package_component` + +For detailed parameter information for each operation, see the [Operations API documentation](TODO:reference_versioned_docs/version-v4/operations-api/operations.md "Complete operations list"). + +## Command Examples + +### Database Operations + +**Describe a database**: + +```bash +harper describe_database database=dev +``` + +**Describe a table** (with YAML output): + +```bash +harper describe_table database=dev table=dog +``` + +**Example Output**: +```yaml +schema: dev +name: dog +hash_attribute: id +audit: true +schema_defined: false +attributes: + - attribute: id + is_primary_key: true + - attribute: name + indexed: true +clustering_stream_name: 3307bb542e0081253klnfd3f1cf551b +record_count: 10 +last_updated_record: 1724483231970.9949 +``` + +:::tip +For detailed information on database and table structures, see the [Database Reference](TODO:reference_versioned_docs/version-v4/database/overview.md "Database reference documentation"). +::: + +### Data Operations + +**Search by ID** (with JSON output): + +```bash +harper search_by_id database=dev table=dog ids='["1"]' get_attributes='["*"]' json=true +``` + +**Search by value**: + +```bash +harper search_by_value table=dog search_attribute=name search_value=harper get_attributes='["id", "name"]' +``` + +:::tip +For more information on querying data, see the [REST Reference](TODO:reference_versioned_docs/version-v4/rest/overview.md "REST API reference") and [GraphQL Querying](TODO:reference_versioned_docs/version-v4/graphql-querying/overview.md "GraphQL querying reference"). +::: + +### Configuration Operations + +**Set configuration**: + +```bash +harper set_configuration logging_level=error +``` + +**Get configuration**: + +```bash +harper get_configuration +``` + +:::tip +For comprehensive configuration options, see the [Configuration Reference](TODO:reference_versioned_docs/version-v4/configuration/overview.md "Configuration reference"). +::: + +### Component Operations + +**Deploy a component**: + +```bash +harper deploy_component project=my-cool-app package=https://github.com/HarperDB/application-template +``` + +**Get all components**: + +```bash +harper get_components +``` + +**Note**: `deploy` is an alias for `deploy_component`: + +```bash +harper deploy project=my-app package=https://github.com/user/repo +``` + +:::tip +For more information on components and applications, see the [Components Reference](TODO:reference_versioned_docs/version-v4/components/overview.md "Components reference"). +::: + +### User and Role Operations + +**List users**: + +```bash +harper list_users +``` + +**List roles**: + +```bash +harper list_roles +``` + +:::tip +For detailed information on users, roles, and authentication, see the [Security Reference](TODO:reference_versioned_docs/version-v4/security/overview.md "Security reference"). +::: + +## Remote Operations + +All CLI operations can be executed on remote Harper instances. See [CLI Overview - Remote Operations](./overview.md#remote-operations) for details on authentication and remote execution. + +### Remote Component Deployment + +When using remote operations, you can deploy a local component or application to the remote instance. + +**Deploy current directory**: + +If you omit the `package` parameter, the current directory will be packaged and deployed: + +```bash +harper deploy target=https://server.com:9925 +``` + +**Note**: `deploy` is an alias for `deploy_component`. + +**Deploy to clustered environment**: + +For clustered environments, use the `replicated=true` parameter to ensure the deployment is replicated to all nodes: + +```bash +harper deploy target=https://server.com:9925 replicated=true +``` + +**Restart after deployment** (with replication): + +After deploying to a clustered environment, restart all nodes to apply changes: + +```bash +harper restart target=https://server.com:9925 replicated=true +``` + +For more information on Harper applications and components, see: +- [Applications](TODO:reference_versioned_docs/version-v4/applications/overview.md "Applications reference") - Application architecture and structure +- [Deploying Harper Applications](TODO:learn_link "Deploying applications guide") - Step-by-step deployment guide + +## Parameter Formatting + +### String Parameters + +Simple string values can be passed directly: + +```bash +harper describe_table database=dev table=dog +``` + +### Array Parameters + +Array parameters must be quoted and formatted as JSON: + +```bash +harper search_by_id database=dev table=dog ids='["1","2","3"]' +``` + +### Object Parameters + +Object parameters are not supported via CLI. For operations requiring complex nested objects, use: +- The [Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API") via HTTP +- A custom script or tool + +### Boolean Parameters + +Boolean values can be passed as strings: + +```bash +harper get_configuration json=true +harper deploy target=https://server.com:9925 replicated=true +``` + +## Output Formatting + +### YAML (Default) + +By default, CLI operation results are formatted as YAML for readability: + +```bash +harper describe_table database=dev table=dog +``` + +### JSON + +Pass `json=true` to get JSON output (useful for scripting): + +```bash +harper describe_table database=dev table=dog json=true +``` + +## Scripting and Automation + +The Operations API commands through the CLI are ideal for: + +- Build and deployment scripts +- Automation workflows +- CI/CD pipelines +- Administrative tasks +- Monitoring and health checks + +**Example Script**: + +```bash +#!/bin/bash + +# Deploy component to remote cluster +export CLI_TARGET_USERNAME=HDB_ADMIN +export CLI_TARGET_PASSWORD=$SECURE_PASSWORD + +harper deploy \ + target=https://cluster-node-1.example.com:9925 \ + replicated=true \ + package=https://github.com/myorg/my-component + +# Restart the cluster +harper restart \ + target=https://cluster-node-1.example.com:9925 \ + replicated=true + +# Check status +harper get_components \ + target=https://cluster-node-1.example.com:9925 \ + json=true +``` + +## Limitations + +The following operation types are **not supported** via CLI: + +- Operations requiring complex nested JSON structures +- Operations with array-of-objects parameters +- File upload operations +- Streaming operations + +For these operations, use the [Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API") directly via HTTP. + +## See Also + +- [CLI Overview](./overview.md) - General CLI information +- [CLI Commands](./commands.md) - Core CLI commands +- [Operations API Overview](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API overview") - Operations API documentation +- [Operations API Reference](TODO:reference_versioned_docs/version-v4/operations-api/operations.md "Operations reference") - Complete operations list +- [CLI Authentication](./authentication.md) - Authentication details diff --git a/reference_versioned_docs/version-v4/cli/overview.md b/reference_versioned_docs/version-v4/cli/overview.md new file mode 100644 index 00000000..62978525 --- /dev/null +++ b/reference_versioned_docs/version-v4/cli/overview.md @@ -0,0 +1,196 @@ +--- +title: Harper CLI Overview +--- + + + + + + + +# Harper CLI Overview + +The Harper command line interface (CLI) is used to administer self-installed Harper instances. + +## Installation + +Available since: v4.1.0 + +Harper is typically installed globally via npm: + +```bash +npm i -g harperdb +``` + +The installation includes the Harper CLI, which provides comprehensive management capabilities for local and remote Harper instances. + +For detailed installation instructions, see the [Getting Started / Install And Connect Harper](https://docs.harperdb.io/docs/getting-started/install-and-connect-harper) guide. + +## Command Name + +Changed in: v4.7.0 + +The CLI command is `harper`. From v4.1.0 to v4.6.x, the command was only available as `harperdb`. Starting in v4.7.0, the preferred command is `harper`, though `harperdb` continues to work as an alias for backward compatibility. + +**Examples**: +```bash +# Modern usage (v4.7.0+) +harper +harper describe_table database=dev table=dog + +# Legacy usage (still supported) +harperdb +harperdb describe_table database=dev table=dog +``` + +All examples in this documentation use `harper`. + +## General Usage + +The primary way to use Harper is to run the `harper` command. When you run `harper`: + +- If Harper is not installed, it will guide you through the installation process +- Once installed, it runs Harper in the foreground as a standard process +- This makes it compatible with systemd, Docker, and other process management tools +- Output logs directly to the console for easy monitoring + +The CLI supports two main categories of commands: + +1. **System Commands** - Core Harper management commands (start, stop, restart, status, etc.) +2. **Operations API Commands** - Execute operations from the Operations API directly via the CLI + +Both system and operations commands can be executed on local or remote Harper instances. For remote operations, authentication credentials can be provided via command parameters or environment variables. + +### CLI Installation Targeting + +By default, the CLI targets the Harper installation path stored in `~/.harperdb/hdb_boot_properties.file`. You can override this to target a specific Harper installation by specifying the `--ROOTPATH` command line argument or the `ROOTPATH` environment variable. + +**Example: Target a specific installation**: + +```bash +# Using command line argument +harper status --ROOTPATH /custom/path/to/hdb + +# Using environment variable +export ROOTPATH=/custom/path/to/hdb +harper status +``` + +### Process ID File + +When Harper is running, the process identifier (PID) is stored in a file named `hdb.pid` located in the Harper installation directory. This file can be used by external process management tools or scripts to monitor or manage the Harper process. + +**Location**: `/hdb.pid` + +**Example**: +```bash +# Read the PID +cat /path/to/hdb/hdb.pid + +# Use with external tools +kill -0 $(cat /path/to/hdb/hdb.pid) # Check if process is running +``` + +## System Management Commands + +| Command | Description | Available Since | +|---------|-------------|-----------------| +| `harper` | Run Harper in foreground mode (default behavior) | v4.1.0 | +| `harper run ` | Run Harper application from any directory | v4.2.0 | +| `harper dev ` | Run Harper in dev mode with auto-restart and console logging | v4.2.0 | +| `harper restart` | Restart Harper | v4.1.0 | +| `harper start` | Start Harper in background (daemon mode) | v4.1.0 | +| `harper stop` | Stop a running Harper instance | v4.1.0 | +| `harper status` | Display Harper and clustering status | v4.1.0 | +| `harper version` | Show installed Harper version | v4.1.0 | +| `harper renew-certs` | Renew Harper-generated self-signed certificates | v4.1.0 | +| `harper copy-db ` | Copy a database with compaction | v4.1.0 | +| `harper help` | Display all available CLI commands | v4.1.0 | + +See [CLI Commands](./commands.md) for detailed documentation on each command. + +## Operations API Commands + +Added in: v4.3.0 (confirmed via release notes) + +The Harper CLI supports executing most operations from the [Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API overview") directly from the command line. This includes operations that do not require complex nested parameters. + +**Syntax**: `harper =` + +**Output Format**: Results are formatted as YAML by default. Pass `json=true` for JSON output. + +**Examples**: + +```bash +# Describe a table +harper describe_table database=dev table=dog + +# Set configuration +harper set_configuration logging_level=error + +# Deploy a component +harper deploy_component project=my-app package=https://github.com/user/repo + +# Get all components +harper get_components + +# Search by ID (JSON output) +harper search_by_id database=dev table=dog ids='["1"]' json=true + +# SQL query +harper sql sql='select * from dev.dog where id="1"' +``` + +See [Operations API Commands](./operations-api-commands.md) for the complete list of available operations. + +## Remote Operations + +Changed in: v4.3.0 (expanded remote operations support) + +The CLI can execute operations on remote Harper instances by passing the `target` parameter with the HTTP address of the remote instance. + +**Authentication**: Provide credentials via: +- Parameters: `username= password=` +- Environment variables: `CLI_TARGET_USERNAME` and `CLI_TARGET_PASSWORD` + +See [CLI Authentication](./authentication.md) for detailed information on authentication methods and best practices. + +**Example: CLI Target Environment Variables**: + +```bash +export CLI_TARGET_USERNAME=HDB_ADMIN +export CLI_TARGET_PASSWORD=password +harper describe_database database=dev target=https://server.com:9925 +``` + +**Example: CLI Options**: + +```bash +harper describe_database database=dev target=https://server.com:9925 username=HDB_ADMIN password=password +``` + +## Development Mode + +Added in: v4.2.0 (confirmed via release notes) + +For local application and component development, use `harper dev`: + +```bash +harper dev /path/to/app +``` + +**Features**: +- Console logging for immediate feedback +- Debugging enabled +- Auto-restart on file changes +- Ideal for rapid iteration during development + +See [CLI Commands](./commands.md) for detailed information on `harper dev` and other development commands. + +## See Also + +- [CLI Commands](./commands.md) - Detailed reference for each CLI command +- [Operations API Commands](./operations-api-commands.md) - Operations available through CLI +- [CLI Authentication](./authentication.md) - Authentication mechanisms +- [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md "Configuration overview") - Harper configuration options +- [Operations API](TODO:reference_versioned_docs/version-v4/operations-api/overview.md "Operations API") - Full operations API reference diff --git a/reference_versioned_sidebars/version-v4-sidebars.json b/reference_versioned_sidebars/version-v4-sidebars.json index 5a3f77b6..6229878b 100644 --- a/reference_versioned_sidebars/version-v4-sidebars.json +++ b/reference_versioned_sidebars/version-v4-sidebars.json @@ -1,8 +1,37 @@ { - "docsSidebar": [ + "referenceSidebar": [ { - "type": "autogenerated", - "dirName": "." + "type": "doc", + "id": "index", + "label": "Welcome" + }, + { + "type": "category", + "label": "CLI", + "collapsible": false, + "className": "learn-category-header", + "items": [ + { + "type": "doc", + "id": "cli/overview", + "label": "Overview" + }, + { + "type": "doc", + "id": "cli/commands", + "label": "Commands" + }, + { + "type": "doc", + "id": "cli/operations-api-commands", + "label": "Operations API Commands" + }, + { + "type": "doc", + "id": "cli/authentication", + "label": "Authentication" + } + ] } ] } diff --git a/v4-docs-execution-procedure.md b/v4-docs-execution-procedure.md index 25181c1e..4c3af8be 100644 --- a/v4-docs-execution-procedure.md +++ b/v4-docs-execution-procedure.md @@ -105,12 +105,14 @@ gh auth status 4. Generate new files in reference_versioned_docs/version-v4/cli/ with: - Inline source comments - Version annotations with confidence levels - - Link placeholders for cross-references - 5. Create migration-context/link-placeholders/cli-link-placeholders.md - 6. Create branch: migration/cli - 7. Commit changes - 8. Open PR using the template from implementation plan - 9. Update v4-docs-migration-map.md status to "In Progress" + - Link placeholders for cross-references (TODO: for external, relative paths for internal) + 5. After generating all files, replace TODO placeholders with relative paths for internal section links + 6. Update reference_versioned_sidebars/version-v4-sidebars.json to add the CLI section + 7. Create migration-context/link-placeholders/cli-link-placeholders.md + 8. Create branch: migration/cli + 9. Commit changes (use git commit --fixup for subsequent changes) + 10. Open PR using the template from implementation plan + 11. Update v4-docs-migration-map.md status to "In Progress" Follow all agent instructions from Part 1 of the implementation plan. ``` @@ -125,8 +127,16 @@ gh auth status - Check PR description follows template - Verify all required sections are filled out - Note quality of content, version annotations, placeholders + - Verify internal links use relative paths (not TODO placeholders) + - Verify sidebar was updated with the new section -5. **Document findings:** +5. **Merge the PR:** + - Use GitHub's "Squash and merge" option + - This combines all fixup commits into a single clean commit + - Development history (with fixup commits) is preserved in the PR for review + - Main branch maintains clean, atomic commits per section + +6. **Document findings:** - What worked well? - What needs improvement? - Any prompt refinements needed? diff --git a/v4-docs-implementation-plan.md b/v4-docs-implementation-plan.md index a17ccdf1..b770ba34 100644 --- a/v4-docs-implementation-plan.md +++ b/v4-docs-implementation-plan.md @@ -37,6 +37,11 @@ For each section in the migration map, the agent should: [JWT Authentication](TODO:reference_versioned_docs/version-v4/security/jwt-authentication.md "Will be created in security section") ``` + **IMPORTANT**: After generating all files in the section, replace TODO placeholders with relative paths for internal section links: + - For links within the same section: Use relative paths like `./filename.md` + - For links to other sections not yet migrated: Keep TODO placeholders + - Example: `[CLI Commands](./commands.md)` NOT `[CLI Commands](TODO:reference_versioned_docs/version-v4/cli/commands.md)` + 7. **Create section-specific link placeholder tracker**: - Store in `migration-context/link-placeholders/` - Named by section: `cli-link-placeholders.md`, `security-link-placeholders.md`, etc. @@ -78,10 +83,48 @@ For each section in the migration map, the agent should: ![Architecture Diagram](TODO:IMAGE) ``` -11. **Create PR** with comprehensive description (template below) +11. **Update the versioned sidebar** at `reference_versioned_sidebars/version-v4-sidebars.json`: + - Add a non-collapsible category for the section + - List all pages in the appropriate order + - Match the pattern from `sidebarsLearn.ts` (non-collapsible with `className: "learn-category-header"`) + - Example: + ```json + { + "type": "category", + "label": "CLI", + "collapsible": false, + "className": "learn-category-header", + "items": [ + { + "type": "doc", + "id": "cli/overview", + "label": "Overview" + } + ] + } + ``` 12. **Update migration-map.md** status to "In Progress" for that section +13. **Git workflow with fixup commits**: + - Create feature branch: `git checkout -b migration/[section-name]` + - Make initial commit with all content files + - Use `git commit --fixup ` for subsequent changes + - This allows easy squashing later while keeping development history clear + - Example: + ```bash + # Initial commit + git add reference_versioned_docs/version-v4/cli/*.md + git commit -m "docs: migrate CLI section to v4 consolidated reference" + + # Subsequent fixes use --fixup + git add reference_versioned_sidebars/version-v4-sidebars.json + git commit --fixup HEAD + ``` + - PRs will be squash-merged to maintain clean history on main branch + +14. **Create PR** with comprehensive description (template below) + ### PR Description Template ```markdown diff --git a/v4-docs-migration-map.md b/v4-docs-migration-map.md index 2983c57a..757249c0 100644 --- a/v4-docs-migration-map.md +++ b/v4-docs-migration-map.md @@ -24,7 +24,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - Current `reference/harper-cli.md` (if exists) - **Merge Required**: Yes - CLI commands added across versions - **Version Annotations**: Track command additions from v4.1 → v4.7 -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.3.0](release-notes/v4-tucker/4.3.0.md) - CLI expansion with operations API commands - [4.2.0](release-notes/v4-tucker/4.2.0.md) - Dev mode (`harperdb dev`, `harperdb run`) @@ -33,7 +33,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: Extract from `versioned_docs/version-4.7/deployments/harper-cli.md` - **Additional Sources**: Compare all versions for command evolution - **Version Annotations**: Each command should note its introduction version -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.3.0](release-notes/v4-tucker/4.3.0.md) - CLI expansion - [4.1.0](release-notes/v4-tucker/4.1.0.md) - Foreground mode changes @@ -42,13 +42,13 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: Extract from `versioned_docs/version-4.7/deployments/harper-cli.md` - **Additional Sources**: `versioned_docs/version-4.3+` (CLI ops api support added in v4.3) - **Version Annotations**: Note v4.3.0 introduction -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.3.0](release-notes/v4-tucker/4.3.0.md) - CLI expansion with operations API ### `reference/cli/authentication.md` - **Primary Source**: New content or extract from CLI docs -- **Status**: Not Started +- **Status**: In Progress ---