> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octopipe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Login

# `octopipe auth login` Command Reference

The `octopipe auth login` command authenticates your local CLI session with the Octopipe cloud service. This step is essential for accessing cloud-specific features and for securely managing pipelines.

## Purpose

* **Authentication:**\
  Validates your credentials against the Octopipe service via direct credentials (API key, username/password, token) **or** via an interactive browser flow.

* **Session Management:**\
  Creates an authenticated session that persists until logout.

## Usage

```bash theme={null}
octopipe auth login [options]
```

**Options**

* `--api-key <key>`\
  **Description:** Provide your unique API key for direct authentication.\
  **Example:** `--api-key ABCDEFG1234567`

* `--username <username>`\
  **Description:** Specify your username for direct authentication (requires `--password`).\
  **Example:** `--username johndoe`

* `--password <password>`\
  **Description:** Specify your password for direct authentication (requires `--username`).\
  **Example:** `--password MySecretPassword`

* `--token <token>`\
  **Description:** Use an existing authentication token if available.\
  **Example:** `--token TOKEN_VALUE`

* `--server <url>`\
  **Description:** Define a custom server URL if you are not using the default Octopipe endpoint.\
  **Example:** `--server https://custom.octopipe.io`

* `--port <port>`\
  **Description:** Local port for the callback server if using the browser-based flow.\
  **Default:** `8765`

* `--timeout <seconds>`\
  **Description:** Timeout in seconds before the browser-based login flow fails.\
  **Default:** `120`

## Detailed Behavior

1. **Direct Credential Validation:**
   * If you pass an `--api-key`, the CLI will authenticate directly by sending the API key to the server.
   * If you pass `--username` and `--password`, the CLI will attempt username/password authentication.
   * If you pass `--token`, the CLI will simply store this token, bypassing the login flow.

2. **Browser-Based Flow:**
   * If no direct credentials are provided, the CLI will attempt the interactive login flow by opening your browser and listening on a local port for a callback.
   * Once authenticated, the token is stored locally.

3. **Session Persistence:**
   * The token is saved in your local configuration (usually `~/.octopipe/auth.json`), so you don’t need to log in repeatedly.

4. **Security Measures:**
   * Passwords and tokens are not logged. All sensitive information is encrypted during transmission.
   * Always store credentials safely.

## Examples

**Example 1: Logging in with an API Key**

```bash theme={null}
octopipe auth login --api-key ABCDEFG1234567
```

**Example 2: Logging in with Username and Password**

```bash theme={null}
octopipe auth login --username johndoe --password MySecretPassword
```

**Example 3: Using an Existing Token**

```bash theme={null}
octopipe auth login --token TOKEN_VALUE
```

**Example 4: Browser-Based Flow with Custom Port**

```bash theme={null}
octopipe auth login --port 9999 --timeout 120
```

## Best Practices

* **Keep Your API Key Secure:**\
  Never expose your API key or password in shared scripts or public repositories.

* **Session Management:**\
  Regularly log out (`octopipe auth logout`) if you’re using a shared machine.

* **Token Renewal:**\
  In case your session expires, re-run the login command to refresh your token.

## Troubleshooting

* **Invalid Credentials:**\
  Check for typos in API key, username, or password.

* **Network Issues:**\
  Verify that you have an active internet connection, especially when using a custom server URL.

* **Server Errors:**\
  If the server returns an error, refer to the troubleshooting section of our documentation for further guidance.

## Conclusion

The `octopipe auth login` command is essential for establishing a secure, authenticated session with the Octopipe service. By following the best practices and examples provided, you can ensure smooth and secure access to all Octopipe functionalities.