{"id":9145,"library":"oauth-cli-kit","title":"OAuth CLI Kit","description":"oauth-cli-kit (version 0.1.3) provides reusable helpers for implementing the OAuth 2.0 Authorization Code Grant flow with PKCE (Proof Key for Code Exchange) in command-line applications. It simplifies the process by handling browser interaction for user authorization and setting up a temporary local server for the redirect URI callback. The library aims for a stable release cadence but is currently in early development (0.x.x), meaning API changes are possible.","status":"active","version":"0.1.3","language":"en","source_language":"en","source_url":"https://github.com/nickolabs/oauth-cli-kit","tags":["oauth","oauth2","pkce","cli","authentication","authorization","security"],"install":[{"cmd":"pip install oauth-cli-kit","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"HTTP client for making requests to OAuth endpoints (authorization, token exchange).","package":"httpx"},{"reason":"Provides cryptographic helpers for PKCE (Proof Key for Code Exchange).","package":"python-pkce"},{"reason":"Used for building the command-line interface around the OAuth flow (a core intended use case).","package":"typer"},{"reason":"Enhances console output with rich formatting for a better user experience.","package":"rich"}],"imports":[{"symbol":"OAuthCliApp","correct":"from oauth_cli_kit import OAuthCliApp"}],"quickstart":{"code":"import os\nfrom oauth_cli_kit import OAuthCliApp\n\ndef main():\n    # Replace these placeholders with your actual OAuth provider details or set as environment variables.\n    client_id = os.environ.get(\"OAUTH_CLI_KIT_CLIENT_ID\", \"YOUR_CLIENT_ID_HERE\")\n    auth_url = os.environ.get(\"OAUTH_CLI_KIT_AUTH_URL\", \"https://example.com/oauth/authorize\")\n    token_url = os.environ.get(\"OAUTH_CLI_KIT_TOKEN_URL\", \"https://example.com/oauth/token\")\n    redirect_uri = os.environ.get(\"OAUTH_CLI_KIT_REDIRECT_URI\", \"http://localhost:8000\")\n    scope = os.environ.get(\"OAUTH_CLI_KIT_SCOPE\", \"profile email openid\")\n\n    if client_id == \"YOUR_CLIENT_ID_HERE\" or auth_url == \"https://example.com/oauth/authorize\":\n        print(\"WARNING: Using placeholder OAuth credentials. \")\n        print(\"Please configure OAUTH_CLI_KIT_CLIENT_ID, OAUTH_CLI_KIT_AUTH_URL, \")\n        print(\"OAUTH_CLI_KIT_TOKEN_URL environment variables or replace placeholders in the code \")\n        print(\"with your actual OAuth provider details to run a successful flow.\")\n        print(f\"  Attempting with: Client ID={client_id}, Auth URL={auth_url}, Token URL={token_url}\")\n\n    print(\"Initiating OAuth 2.0 PKCE flow...\")\n\n    try:\n        oauth_app = OAuthCliApp(\n            client_id=client_id,\n            auth_url=auth_url,\n            token_url=token_url,\n            redirect_uri=redirect_uri,\n            scope=scope,\n        )\n        token_response = oauth_app.run_flow() # This call opens browser and waits\n        print(\"\\n--- OAuth Flow Successful ---\")\n        print(f\"Access Token: {token_response.access_token[:10]}... (truncated)\")\n        if token_response.refresh_token:\n            print(f\"Refresh Token: {token_response.refresh_token[:10]}... (truncated)\")\n        print(f\"Token Type: {token_response.token_type}\")\n        print(f\"Expires In: {token_response.expires_in} seconds\")\n        if token_response.id_token:\n            print(f\"ID Token (JWT): {token_response.id_token[:10]}... (truncated)\")\n\n    except Exception as e:\n        print(f\"\\n--- OAuth Flow Failed ---\")\n        print(f\"Error: {e}\")\n        print(\"Please check your configuration, network connection, and browser interaction.\")\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"This quickstart demonstrates how to initiate an OAuth 2.0 PKCE flow using `OAuthCliApp`. It will open a browser for user authentication and then process the callback locally. Remember to replace placeholder URLs and client IDs with your actual provider details, ideally via environment variables, for a successful authentication."},"warnings":[{"fix":"Review the GitHub repository's changelog or releases notes before upgrading, especially when moving between minor versions (e.g., 0.1.x to 0.2.x).","message":"As a 0.x.x version library, the API is not yet stable. Expect potential breaking changes in minor releases as the library evolves.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Verify that your OAuth provider's registered redirect URI exactly matches the `redirect_uri` you pass to `OAuthCliApp` and that no firewall or other process is blocking port 8000 (or your chosen custom port).","message":"The library automatically starts a temporary local HTTP server to handle the OAuth redirect URI (e.g., `http://localhost:8000`). Ensure this URI is registered with your OAuth provider and is accessible on the client machine.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult your OAuth provider's documentation. If PKCE is not supported, you might need to use a different library or a different flow entirely, as this library is strongly oriented towards PKCE.","message":"By default, the library implements the Authorization Code Grant flow with PKCE. Confirm that your OAuth 2.0 provider supports PKCE, as some older or less standard implementations might not.","severity":"gotcha","affected_versions":"All"},{"fix":"Implement a secure token storage mechanism (e.g., keyring, encrypted file) and a token refreshing strategy using the obtained refresh token within your CLI application.","message":"The `oauth-cli-kit` only facilitates obtaining access and refresh tokens. It does not handle the secure storage, retrieval, or refreshing of these tokens. This must be implemented by your application.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the `redirect_uri` configured in your application and with the OAuth provider is `http://localhost:8000` (or your chosen custom port). Check if another process is already using port 8000, and ensure no firewalls are blocking it. You can specify a different `redirect_uri` port if needed.","cause":"The local redirect server failed to start or receive the authorization code, often due to an incorrect redirect URI configuration or a port conflict.","error":"HTTPX_CLI_APP_CALLBACK_FAILURE"},{"fix":"Verify that your OAuth provider correctly supports and implements PKCE. Ensure no intermediate proxies are modifying the request/response. Double-check your `client_id` and other OAuth configuration details.","cause":"The OAuth provider returned an authorization code, but the PKCE code_verifier did not match during token exchange, indicating a mismatch or an unsupported provider.","error":"oauth_cli_kit.errors.OAuthCliKitError: PKCE verification failed"},{"fix":"Explicitly install `typer`: `pip install typer` or ensure you are installing `oauth-cli-kit` in a clean environment where dependencies are resolved normally.","cause":"Although `typer` is a dependency of `oauth-cli-kit`, some environments (especially if installing with `--no-deps` or in custom setups) might not automatically install it.","error":"ModuleNotFoundError: No module named 'typer'"},{"fix":"Manually copy the authorization URL (which is usually printed to the console before the error) and paste it into your web browser. Complete the authentication flow there, and the local server should still capture the redirect.","cause":"The library failed to automatically open the default web browser to the authorization URL, often due to environmental issues or lack of a default browser configuration.","error":"oauth_cli_kit.errors.OAuthCliKitError: Failed to open browser: ..."}]}