Login cli

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 <URL>
+```
+
+Type in your cluster's username and password. Then, run the `harper deploy` command:
 
 ```bash
 harper deploy \
   target=<URL> \
-  username=<username> \
-  password=<password> \
   project=first-harper-app \
   restart=true \
   replicated=true

reference/cli/authentication.md

@@ -34,44 +34,102 @@ 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 <URL>`, 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**:
 
 ```bash
 #!/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,19 +267,19 @@ 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**:
    Ensure you used `export`, not just assignment:
 
    ```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**:

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 <URL>
+```
+
+**Optional Parameters**:
+
+- `<URL>` - The URL of the Harper instance to log in to.
+
+**Prompts**:
+
+You'll be asked to type in the following information:
+
+- `<URL>` - If a URL parameter is not provided, you'll be prompted to enter the URL of the Harper instance to log in to.
+- `<username>` - Harper admin username.
+- `<password>` - 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 <URL>
+```
+
+**Optional Parameters**:
+
+- `<URL>` - 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`

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 \

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=<user> password=<pass>`
-- 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=<user> password=<pass>`
 
 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
 ```
 

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 <remote>
+# Provide your username and password when prompted
+
+# Subsequently deploy without credentials
 harper deploy \
   project=<name> \
   package=<package> \
-  username=<username> \
-  password=<password> \
   target=<remote> \
   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=<username>
-export CLI_TARGET_PASSWORD=<password>
+export HARPER_CLI_USERNAME=<username>
+export HARPER_CLI_PASSWORD=<password>
 harper deploy \
   project=<name> \
   package=<package> \
@@ -94,6 +97,19 @@ harper deploy \
   replicated=true
 ```
 
+Or directly via command parameters (not recommended for production):
+
+```sh
+harper deploy \
+  project=<name> \
+  package=<package> \
+  username=<username> \
+  password=<password> \
+  target=<remote> \
+  restart=true \
+  replicated=true
+```
+
 ### Package Sources
 
 When deploying remotely, the `package` field can be any valid npm dependency value: