​
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

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

octopipe auth login --api-key ABCDEFG1234567

Example 2: Logging in with Username and Password

octopipe auth login --username johndoe --password MySecretPassword

Example 3: Using an Existing Token

octopipe auth login --token TOKEN_VALUE

Example 4: Browser-Based Flow with Custom Port

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.