0
# CLI Tool
1

2
Command-line tool for obtaining OAuth 2.0 credentials during development and testing. Provides an interactive authentication flow with options for credential storage and scope configuration.
3

4
## Installation
5

6
The CLI tool requires additional dependencies:
7

8
```bash
9
pip install google-auth-oauthlib[tool]
10
```
11

12
## Usage
13

14
```bash
15
google-oauthlib-tool --client-secrets CLIENT_SECRETS.json --scope SCOPE [OPTIONS]
16
```
17

18
## Capabilities
19

20
### Command-Line Interface
21

22
Interactive OAuth 2.0 credential acquisition tool for development workflows.
23

24
```bash { .api }
25
google-oauthlib-tool
26
  --client-secrets <client_secret_json_file>  # Required: Path to OAuth2 client secret JSON
27
  --scope <oauth2_scope>                      # Required: API scopes (multiple allowed)
28
  [--save]                                    # Optional: Save credentials to file
29
  [--credentials <oauth2_credentials>]        # Optional: Path to store credentials
30
```
31

32
### Command Options
33

34
```python { .api }
35
# CLI configuration constants
36
APP_NAME: str = "google-oauthlib-tool"
37
DEFAULT_CREDENTIALS_FILENAME: str = "credentials.json"
38

39
def main(
40
    client_secrets: str,      # Path to client secrets JSON file
41
    scope: tuple,             # Multiple scopes can be specified
42
    save: bool = False,       # Save credentials to file
43
    credentials: str = None   # Path to save credentials (default: app dir)
44
):
45
    """
46
    Main CLI function for OAuth credential acquisition.
47
    
48
    Performs OAuth 2.0 Authorization Code flow to obtain credentials
49
    for testing applications or development workflows.
50
    """
51
```
52

53
## Usage Examples
54

55
### Basic Usage
56

57
```bash
58
# Obtain credentials for BigQuery access
59
google-oauthlib-tool \
60
  --client-secrets client_secrets.json \
61
  --scope https://www.googleapis.com/auth/bigquery
62
```
63

64
### Multiple Scopes
65

66
```bash
67
# Request multiple API scopes
68
google-oauthlib-tool \
69
  --client-secrets client_secrets.json \
70
  --scope https://www.googleapis.com/auth/cloud-platform \
71
  --scope https://www.googleapis.com/auth/userinfo.email
72
```
73

74
### Save Credentials to File
75

76
```bash
77
# Save credentials for reuse
78
google-oauthlib-tool \
79
  --client-secrets client_secrets.json \
80
  --scope https://www.googleapis.com/auth/drive \
81
  --save \
82
  --credentials my_credentials.json
83
```
84

85
### Custom Credentials Path
86

87
```bash
88
# Specify custom save location
89
google-oauthlib-tool \
90
  --client-secrets client_secrets.json \
91
  --scope https://www.googleapis.com/auth/storage \
92
  --save \
93
  --credentials /path/to/credentials.json
94
```
95

96
## Workflow
97

98
1. **Load client secrets**: Reads OAuth client configuration from JSON file
99
2. **Create flow**: Sets up InstalledAppFlow with specified scopes
100
3. **Run local server**: Launches local web server for OAuth redirect
101
4. **Browser authentication**: Opens browser for user consent
102
5. **Token exchange**: Exchanges authorization code for access tokens
103
6. **Output credentials**: Prints or saves credential information
104

105
## Output Formats
106

107
### Console Output (default)
108

109
When `--save` is not specified, credentials are printed to stdout as JSON:
110

111
```json
112
{
113
  "token": "ya29.a0AfH6SMC...",
114
  "refresh_token": "1//-0dGKGb...", 
115
  "token_uri": "https://oauth2.googleapis.com/token",
116
  "client_id": "your-client-id.apps.googleusercontent.com",
117
  "client_secret": "your-client-secret",
118
  "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
119
}
120
```
121

122
### File Output (with --save)
123

124
When `--save` is specified, credentials are saved to file without the access token:
125

126
```json
127
{
128
  "refresh_token": "1//-0dGKGb...",
129
  "token_uri": "https://oauth2.googleapis.com/token", 
130
  "client_id": "your-client-id.apps.googleusercontent.com",
131
  "client_secret": "your-client-secret",
132
  "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
133
}
134
```
135

136
## Default Locations
137

138
### Client Secrets
139

140
No default location - must be specified with `--client-secrets`
141

142
### Saved Credentials
143

144
Default save location (when `--credentials` not specified):
145
- **Linux/macOS**: `~/.config/google-oauthlib-tool/credentials.json`
146
- **Windows**: `%APPDATA%\google-oauthlib-tool\credentials.json`
147

148
## Integration with Development Workflows
149

150
### Python Scripts
151

152
```python
153
# Load saved credentials in Python code
154
import json
155
from google.oauth2.credentials import Credentials
156

157
with open('credentials.json', 'r') as f:
158
    creds_data = json.load(f)
159

160
credentials = Credentials.from_authorized_user_info(creds_data, creds_data['scopes'])
161

162
# Use with Google API clients
163
from google.cloud import storage
164
client = storage.Client(credentials=credentials)
165
```
166

167
### Environment Setup
168

169
```bash
170
# Create credentials for CI/CD or testing
171
google-oauthlib-tool \
172
  --client-secrets ci_client_secrets.json \
173
  --scope https://www.googleapis.com/auth/cloud-platform \
174
  --save \
175
  --credentials test_credentials.json
176

177
# Use in tests
178
export GOOGLE_APPLICATION_CREDENTIALS=test_credentials.json
179
```
180

181
### Development Scripts
182

183
```bash
184
#!/bin/bash
185
# development_setup.sh
186

187
echo "Setting up OAuth credentials for development..."
188

189
google-oauthlib-tool \
190
  --client-secrets config/client_secrets.json \
191
  --scope https://www.googleapis.com/auth/cloud-platform \
192
  --scope https://www.googleapis.com/auth/bigquery \
193
  --save
194

195
echo "Credentials saved. Ready for development."
196
```
197

198
## Error Handling
199

200
Common error scenarios:
201

202
- **Missing client secrets file**: Tool exits with error message
203
- **Invalid client secrets format**: JSON parsing or validation error
204
- **OAuth flow errors**: Network issues, user denial, or invalid configuration
205
- **File permission errors**: Cannot write to credentials save location
206

207
## Security Notes
208

209
- The tool is intended for development and testing only
210
- Access tokens are short-lived and printed to console (unless `--save` used)
211
- Refresh tokens are saved to file when using `--save` option
212
- Protect client secrets and saved credential files appropriately
213
- Consider using separate OAuth clients for development vs production