0
# Authentication & User Management
1

2
Core authentication functionality for managing user credentials and account access. All publishing operations require authentication.
3

4
## Capabilities
5

6
### Login
7

8
Authenticate with Surge platform and store credentials locally for subsequent commands.
9

10
```javascript { .api }
11
/**
12
 * Authenticate user with email/password and store credentials
13
 * @param hooks - Optional lifecycle hooks
14
 * @returns Command function
15
 */
16
function login(hooks?: HookConfig): CommandFunction;
17
```
18

19
**CLI Usage:**
20
```bash
21
surge login
22
```
23

24
Interactive prompts for email and password. Credentials are stored in `.netrc` format for automatic authentication in future commands.
25

26
**Library Usage:**
27
```javascript
28
const surge = require('surge')();
29
surge.login({})(process.argv.slice(2));
30
```
31

32
### Logout
33

34
Remove stored authentication credentials and expire the current session.
35

36
```javascript { .api }
37
/**
38
 * Remove stored credentials and expire session
39
 * @param hooks - Optional lifecycle hooks  
40
 * @returns Command function
41
 */
42
function logout(hooks?: HookConfig): CommandFunction;
43
```
44

45
**CLI Usage:**
46
```bash
47
surge logout
48
```
49

50
**Library Usage:**
51
```javascript
52
surge.logout({})(process.argv.slice(2));
53
```
54

55
### Who Am I
56

57
Display information about the currently authenticated user.
58

59
```javascript { .api }
60
/**
61
 * Display current authenticated user information
62
 * @param hooks - Optional lifecycle hooks
63
 * @returns Command function
64
 */
65
function whoami(hooks?: HookConfig): CommandFunction;
66
```
67

68
**CLI Usage:**
69
```bash
70
surge whoami
71
```
72

73
Displays the email address and account plan of the currently authenticated user.
74

75
**Library Usage:**
76
```javascript
77
surge.whoami({})(process.argv.slice(2));
78
```
79

80
### API Token
81

82
Generate an API token for automation and CI/CD integration.
83

84
```javascript { .api }
85
/**
86
 * Generate API token for programmatic access
87
 * @param hooks - Optional lifecycle hooks
88
 * @returns Command function
89
 */
90
function token(hooks?: HookConfig): CommandFunction;
91
```
92

93
**CLI Usage:**
94
```bash
95
surge token
96
```
97

98
Generates and displays an API token that can be used for automated deployments. Store in environment variable `SURGE_TOKEN` for CI/CD systems.
99

100
**Library Usage:**
101
```javascript
102
surge.token({})(process.argv.slice(2));
103
```
104

105
## Environment Variables
106

107
### Authentication Environment Variables
108

109
- **`SURGE_TOKEN`**: API token for non-interactive authentication
110
- **`TRAVIS_SURGE_TOKEN`**: Legacy Travis CI integration token
111

112
**Usage Example:**
113
```bash
114
export SURGE_TOKEN="your-api-token-here"
115
surge publish ./build example.surge.sh
116
```
117

118
## Credential Storage
119

120
Surge stores authentication credentials in `.netrc` format in the user's home directory. The format follows standard netrc conventions:
121

122
```
123
machine surge.surge.sh
124
  login user@example.com
125
  password api-token-here
126
```
127

128
## Error Handling
129

130
### Common Authentication Errors
131

132
- **Unauthenticated**: No valid credentials found
133
- **Forbidden**: Invalid credentials or expired token
134
- **Client Upgrade Required**: CLI version needs updating
135

136
All authentication commands handle these errors gracefully with informative error messages.