diff --git a/learn/getting-started/create-your-first-application.mdx b/learn/getting-started/create-your-first-application.mdx index c48dab25..93cabf60 100644 --- a/learn/getting-started/create-your-first-application.mdx +++ b/learn/getting-started/create-your-first-application.mdx @@ -357,13 +357,17 @@ Push-based deployments is powered by the Harper CLI and is where your the user w For a true production application, Harper recommends using pull-based deployments so that you can deploy tagged versions of your application repository. But for development and experimentation, push-based is perfectly fine. Later guides will explore pull-based deployment workflows in more detail. -To get started with push-based deployments, open a command line and set the current directory to the application directory. Run the `harper deploy` command using the Fabric cluster's URL, username, and password: +To get started with push-based deployments, open a command line and set the current directory to the application directory. First, log in to your Fabric cluster: + +```bash +harper login +``` + +Type in your cluster's username and password. Then, run the `harper deploy` command: ```bash harper deploy \ target= \ - username= \ - password= \ project=first-harper-app \ restart=true \ replicated=true diff --git a/reference/cli/authentication.md b/reference/cli/authentication.md index 44a424b7..c2d9487a 100644 --- a/reference/cli/authentication.md +++ b/reference/cli/authentication.md @@ -34,28 +34,86 @@ For remote operations (operations executed on a remote Harper instance via the ` ### Authentication Methods -#### Method 1: Environment Variables (Recommended) +#### Method 1: Persistent Login (Recommended for Local Development) -Set the following environment variables to avoid exposing credentials in command history: +Available since: v5.1.0 + +Use `harper login` to store authentication tokens for a specific target. This is the most convenient method for local development as it removes the need to pass credentials with every command. ```bash -export CLI_TARGET_USERNAME=HDB_ADMIN -export CLI_TARGET_PASSWORD=password +# Log in once +harper login https://server.com:9925 +# Provide username and password when prompted + +# Subsequently execute operations without credentials +harper describe_database database=dev target=https://server.com:9925 +harper deploy target=https://server.com:9925 ``` -Then execute remote operations without including credentials in the command: +When you are finished, you can log out to remove the stored token: ```bash -harper describe_database database=dev target=https://server.com:9925 -harper get_components target=https://remote-instance.example.com:9925 +harper logout https://server.com:9925 +``` + +**Benefits**: + +- Credentials are not stored in command history for every operation +- Simplifies frequent remote operations +- No need to maintain environment variables in multiple terminal sessions + +#### Method 2: Environment Variables (Recommended for CI/CD) + +The CLI supports loading environment variables from your shell environment (or optionally from a `.env` file in the current directory). This is the recommended method for CI/CD pipelines and for pre-populating the `target` parameter for specific projects. + +**Supported Variables**: + +- `HARPER_CLI_TARGET` (or `CLI_TARGET`) - Sets the default `target` for CLI commands. +- `HARPER_CLI_USERNAME` (or `CLI_TARGET_USERNAME`) - Harper admin username for the target. +- `HARPER_CLI_PASSWORD` (or `CLI_TARGET_PASSWORD`) - Harper admin password for the target. + +**Example `.env` file**: + +```bash +HARPER_CLI_TARGET=https://example.com:9925 +HARPER_CLI_USERNAME=HDB_ADMIN +HARPER_CLI_PASSWORD=password +``` + +**Manual Environment Variables**: + +Set these variables in your shell to avoid exposing credentials in command history: + +```bash +export HARPER_CLI_USERNAME=HDB_ADMIN +export HARPER_CLI_PASSWORD=password ``` **Benefits**: - Credentials not visible in command history -- More secure for scripting -- Can be set once per session -- Supported by most CI/CD systems +- More secure for scripting and CI/CD systems +- Can be set once per session or project directory +- Automatically populated by `harper login` + +**Automatic `.env` Updates**: + +When you run `harper login `, the CLI will automatically update your `.env` file in your current directory and set `HARPER_CLI_TARGET` to the specified URL. + +```bash +# Automatically sets HARPER_CLI_TARGET in .env +harper login https://my-project.harperdb.cloud +``` + +Then you can run commands without specifying the `target` or credentials (if they are also in `.env` or exported): + +```bash +# Respects HARPER_CLI_TARGET from .env +harper deploy +harper describe_database database=dev +harper get_components +harper logout +``` **Example Script**: @@ -63,15 +121,15 @@ harper get_components target=https://remote-instance.example.com:9925 #!/bin/bash # Set credentials from secure environment -export CLI_TARGET_USERNAME=HDB_ADMIN -export CLI_TARGET_PASSWORD=$SECURE_PASSWORD # from secret manager +export HARPER_CLI_USERNAME=HDB_ADMIN +export HARPER_CLI_PASSWORD=$SECURE_PASSWORD # from secret manager -# Execute operations +# Execute operations without passing credentials or target (if set) harper deploy target=https://prod-server.com:9925 replicated=true harper restart target=https://prod-server.com:9925 replicated=true ``` -#### Method 2: Command Parameters +#### Method 3: Command Parameters Provide credentials directly as command parameters: @@ -121,8 +179,8 @@ target=https://server.example.com:8080 Always use environment variables for credentials in scripts and automation: ```bash -export CLI_TARGET_USERNAME=HDB_ADMIN -export CLI_TARGET_PASSWORD=$SECURE_PASSWORD +export HARPER_CLI_USERNAME=HDB_ADMIN +export HARPER_CLI_PASSWORD=$SECURE_PASSWORD ``` ### 2. Use HTTPS @@ -151,12 +209,12 @@ Store credentials in secure secret management systems: #!/bin/bash # Retrieve credentials from AWS Secrets Manager -export CLI_TARGET_USERNAME=$(aws secretsmanager get-secret-value \ +export HARPER_CLI_USERNAME=$(aws secretsmanager get-secret-value \ --secret-id harper-admin-user \ --query SecretString \ --output text) -export CLI_TARGET_PASSWORD=$(aws secretsmanager get-secret-value \ +export HARPER_CLI_PASSWORD=$(aws secretsmanager get-secret-value \ --secret-id harper-admin-password \ --query SecretString \ --output text) @@ -209,8 +267,8 @@ If environment variables aren't working: 1. **Verify variables are set**: ```bash - echo $CLI_TARGET_USERNAME - echo $CLI_TARGET_PASSWORD + echo $HARPER_CLI_USERNAME + echo $HARPER_CLI_PASSWORD ``` 2. **Export variables**: @@ -218,10 +276,10 @@ If environment variables aren't working: ```bash # Wrong - variable only available in current shell - CLI_TARGET_USERNAME=admin + HARPER_CLI_USERNAME=admin # Correct - variable available to child processes - export CLI_TARGET_USERNAME=admin + export HARPER_CLI_USERNAME=admin ``` 3. **Check variable scope**: diff --git a/reference/cli/commands.md b/reference/cli/commands.md index b7e45f29..24cfbc57 100644 --- a/reference/cli/commands.md +++ b/reference/cli/commands.md @@ -140,6 +140,44 @@ The `harper install` command operates exactly like the [`harper`](#harper) comma **Note**: We recommend using `harper` instead of `harper install` as it provides a consistent workflow for both installation and running Harper. +### `harper login` + +Available since: v5.0.0 + +Log in to a Harper instance to store authentication tokens locally. Once logged in, subsequent commands targeting this instance (via `target`) will automatically use the stored token. + +The CLI also supports `.env` files. When you log in, the `HARPER_CLI_TARGET` environment variable will be automatically added to a `.env` file in your current directory if it exists. This allows you to omit the `target` parameter in subsequent commands within that directory. + +```bash +harper login +``` + +**Optional Parameters**: + +- `` - The URL of the Harper instance to log in to. + +**Prompts**: + +You'll be asked to type in the following information: + +- `` - If a URL parameter is not provided, you'll be prompted to enter the URL of the Harper instance to log in to. +- `` - Harper admin username. +- `` - Harper admin password. + +### `harper logout` + +Available since: v5.0.0 + +Log out of a Harper instance and remove the stored authentication token. + +```bash +harper logout +``` + +**Optional Parameters**: + +- `` - The URL of the Harper instance to log out from. If none is provided, you'll be signed out of all instances. + ## Information Commands ### `harper version` diff --git a/reference/cli/operations-api-commands.md b/reference/cli/operations-api-commands.md index bdf01d6b..e893f42e 100644 --- a/reference/cli/operations-api-commands.md +++ b/reference/cli/operations-api-commands.md @@ -335,15 +335,15 @@ The Operations API commands through the CLI are ideal for: - Administrative tasks - Monitoring and health checks -**Example Script**: +**Check status**: ```bash -#!/bin/bash +# Log in to the cluster +harper login https://cluster-node-1.example.com:9925 -# Deploy component to remote cluster -export CLI_TARGET_USERNAME=HDB_ADMIN -export CLI_TARGET_PASSWORD=$SECURE_PASSWORD +# Provide your cluster's username and password when prompted. +# Deploy component to remote cluster harper deploy \ target=https://cluster-node-1.example.com:9925 \ replicated=true \ diff --git a/reference/cli/overview.md b/reference/cli/overview.md index 73bbd224..66591a9a 100644 --- a/reference/cli/overview.md +++ b/reference/cli/overview.md @@ -103,6 +103,8 @@ kill -0 $(cat /path/to/hdb/hdb.pid) # Check if process is running | `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 login` | Log in to a Harper instance | v5.0.0 | +| `harper logout` | Log out of a Harper instance | v5.0.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 | @@ -153,16 +155,28 @@ The CLI can execute operations on remote Harper instances by passing the `target **Authentication**: Provide credentials via: -- Parameters: `username= password=` -- Environment variables: `CLI_TARGET_USERNAME` and `CLI_TARGET_PASSWORD` +- **Persistent Login**: `harper login` to store tokens (recommended for local development) +- **Environment variables and `.env` files**: Use `HARPER_CLI_TARGET`, `HARPER_CLI_USERNAME`, and `HARPER_CLI_PASSWORD` (recommended for CI/CD and project-specific configuration) +- **Parameters**: `username= password=` See [CLI Authentication](./authentication.md) for detailed information on authentication methods and best practices. +**Example: Persistent Login and `.env`**: + +```bash +# Log in to a specific target +harper login https://server.com:9925 +# This automatically sets HARPER_CLI_TARGET in your local .env file + +# Subsequently execute operations without target or credentials +harper describe_database database=dev +``` + **Example: CLI Target Environment Variables**: ```bash -export CLI_TARGET_USERNAME=HDB_ADMIN -export CLI_TARGET_PASSWORD=password +export HARPER_CLI_USERNAME=HDB_ADMIN +export HARPER_CLI_PASSWORD=password harper describe_database database=dev target=https://server.com:9925 ``` diff --git a/reference/components/applications.md b/reference/components/applications.md index 1147f607..6bff5d15 100644 --- a/reference/components/applications.md +++ b/reference/components/applications.md @@ -68,24 +68,27 @@ harper deploy \ ## Remote Management -Managing applications on a remote Harper instance uses the same operations as local management. The key difference is specifying a `target` along with credentials: +Managing applications on a remote Harper instance uses the same operations as local management. The recommended approach is to log in first using `harper login` to store an authentication token: ```sh +# Log in once +harper login +# Provide your username and password when prompted + +# Subsequently deploy without credentials harper deploy \ project= \ package= \ - username= \ - password= \ target= \ restart=true \ replicated=true ``` -Credentials can also be provided via environment variables: +Alternatively, credentials can be provided via environment variables (recommended for CI/CD): ```sh -export CLI_TARGET_USERNAME= -export CLI_TARGET_PASSWORD= +export HARPER_CLI_USERNAME= +export HARPER_CLI_PASSWORD= harper deploy \ project= \ package= \ @@ -94,6 +97,19 @@ harper deploy \ replicated=true ``` +Or directly via command parameters (not recommended for production): + +```sh +harper deploy \ + project= \ + package= \ + username= \ + password= \ + target= \ + restart=true \ + replicated=true +``` + ### Package Sources When deploying remotely, the `package` field can be any valid npm dependency value: