You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -34,17 +35,21 @@ The CLI supports **PowerSync Cloud** for creating instances, deploying config, p
34
35
Cloud commands require a PowerSync **personal access token (PAT)**. You can authenticate in two ways:
35
36
36
37
**1. Interactive login (recommended for local use)**
37
-
Run **`powersync login`**. You can either open a browser to create a token in the [PowerSync Dashboard](https://dashboard.powersync.com/account/access-tokens/create) or paste an existing token. On **macOS**, the token is stored in Keychain so you don’t need to pass it again. On **Windows and Linux**, secure storage is not yet supported—use the **`TOKEN`** environment variable instead (see below).
38
+
Run **`powersync login`**. You can either open a browser to create a token in the [PowerSync Dashboard](https://dashboard.powersync.com/account/access-tokens/create) or paste an existing token.
39
+
40
+
- If secure storage is available, the token is saved there (for example, macOS Keychain).
41
+
- If secure storage is unavailable, the CLI asks for confirmation before storing the token in plaintext at **`$XDG_CONFIG_HOME/powersync/config.yaml`** (or **`~/.config/powersync/config.yaml`** when `XDG_CONFIG_HOME` is unset).
42
+
- If you decline, login exits without storing a token.
38
43
39
-
**2. Environment variable (CI, scripts, or when not using macOS)**
44
+
**2. Environment variable (CI, scripts, or non-persistent use)**
40
45
Set **`TOKEN`** to your PAT. The CLI uses **`TOKEN`** when set; otherwise it uses the token from **`powersync login`**. Example:
To stop using stored credentials, run **`powersync logout`**.
52
+
To stop using stored credentials, run **`powersync logout`**. This clears the stored token from the active backend (secure storage or config-file fallback).
48
53
49
54
## Creating a new instance
50
55
@@ -99,7 +104,7 @@ The CLI can run a subset of commands against **self-hosted** PowerSync instances
99
104
For any self-hosted instance (local or remote), you must link the running API to the CLI and configure an API key. On the **server** (your PowerSync instance config), define the tokens that are valid in **`service.yaml`**:
- dev-token-do-not-use-in-production # or use !env MY_API_TOKEN for secrets
@@ -108,7 +113,7 @@ api:
108
113
Then tell the CLI which token to use when running commands. Run **`powersync link self-hosted --api-url <url>`** to write **`cli.yaml`** with the API URL, and either set the **`TOKEN`** environment variable or set **`api_key`** in **`cli.yaml`**:
109
114
110
115
```yaml
111
-
# powersync/cli.yaml (self-hosted)
116
+
# powersync/cli.yaml (self-hosted)
112
117
type: self-hosted
113
118
api_url: https://powersync.example.com
114
119
api_key: !env TOKEN # or a literal value matching one of the tokens in service.yaml
@@ -139,11 +144,12 @@ Only some CLI commands work with self-hosted instances. Supported commands inclu
139
144
140
145
# Known Limitations
141
146
142
-
- **Login secure storage**: Secure storage for auth tokens is only supported on macOS (via Keychain). On Windows and Linux, `powersync login` will not persist credentials; use the `TOKEN` environment variable instead for Cloud commands.
147
+
- **Plaintext fallback storage**: When secure storage is unavailable, login can store the token in plaintext config (`$XDG_CONFIG_HOME/powersync/config.yaml` or `~/.config/powersync/config.yaml`) only after explicit confirmation.
Copy file name to clipboardExpand all lines: cli/src/commands/login.ts
+13-7Lines changed: 13 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -5,19 +5,25 @@ import { startPATLoginServer } from '../api/login-server.js';
5
5
6
6
exportdefaultclassLoginextendsPowerSyncCommand{
7
7
staticdescription=
8
-
'Store a PowerSync auth token (PAT) in secure storage so later Cloud commands run without passing a token. Use TOKEN env var for CI or scripts instead.';
9
-
staticsummary='Store auth token in secure storage for Cloud commands.';
8
+
'Store a PowerSync auth token (PAT) in secure storage so later Cloud commands run without passing a token. If secure storage is unavailable, login can optionally store it in a local config file. Use TOKEN env var for CI or scripts instead.';
9
+
staticsummary='Store auth token for Cloud commands.';
10
10
11
11
asyncrun(): Promise<void>{
12
12
this.parse(Login);
13
13
14
14
const{ authentication, storage }=Services;
15
+
constshouldUseInsecureStorage=
16
+
!storage.capabilities.supportsSecureStorage&&
17
+
(awaitconfirm({
18
+
message: `Keychain storage is unavailable on this platform. Store token in plaintext at ${storage.insecureStoragePath}? Set the ${ux.colorize('blue','TOKEN')} environment variable instead to avoid this.`,
19
+
default: false
20
+
}));
15
21
16
-
if(!storage.capabilities.supportsSecureStorage){
17
-
this.styledError({
18
-
message: 'Secure storage is not yet supported on this platform.',
19
-
suggestions: [`Export and use the ${ux.colorize('blue','TOKEN')} environment variable for commands.`]
'Remove the stored PowerSync auth token from secure storage. Cloud commands will no longer use stored credentials until you run login again.';
8
-
staticsummary='Remove stored auth token from secure storage.';
7
+
'Remove the stored PowerSync auth token from secure storage or local fallback config storage. Cloud commands will no longer use stored credentials until you run login again.';
Copy file name to clipboardExpand all lines: docs/usage.md
+18-5Lines changed: 18 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -76,7 +76,7 @@ The sections below split usage by **Cloud** and **Self-hosted**, then provide re
76
76
77
77
# Cloud usage
78
78
79
-
Authentication is usually the first step. Use `powersync login` to store a token in secure storage (e.g. macOS Keychain), or set the `TOKEN` environment variable if you prefer not to persist the token. See [Authentication (Tokens)](#authentication-tokens) for details.
79
+
Authentication is usually the first step. Use `powersync login` to store a token, or set the `TOKEN` environment variable. Storage behavior depends on platform capabilities and your login choice; see [Authentication (Tokens)](#authentication-tokens) for details.
80
80
81
81
## Creating a new Cloud instance
82
82
@@ -157,10 +157,13 @@ Use `--api-url` with link file or `API_URL` and `TOKEN` when you prefer not to l
157
157
158
158
# Authentication (Tokens)
159
159
160
-
Cloud commands need an auth token (e.g. a PowerSync PAT). You can supply it in two ways; the CLI uses the first that is available:
160
+
Cloud commands need an auth token (e.g. a PowerSync PAT). The CLI uses the first available source:
161
161
162
162
1.**Environment variable** — `TOKEN`
163
-
2.**Stored via login** — token saved by `powersync login` (secure storage, e.g. macOS Keychain)
163
+
2.**Stored via login**
164
+
165
+
-**Secure storage** when available (for example, macOS Keychain)
166
+
-**Config-file fallback** when secure storage is unavailable **and** you explicitly confirm at login
164
167
165
168
**Environment variable** — useful for CI, scripts, or one-off runs:
**Stored via login** — convenient for local use; token is stored securely and reused:
181
+
**Stored via login** — convenient for local use; token is reused by later commands:
179
182
180
183
```bash
181
184
powersync login
@@ -184,7 +187,17 @@ powersync login
184
187
powersync fetch config
185
188
```
186
189
187
-
Login is supported on macOS (other platforms coming soon). If you use another platform or prefer not to store the token, set `TOKEN` in the environment instead.
190
+
If secure storage is not available, `powersync login` asks whether to store the token in plaintext at:
191
+
192
+
```bash
193
+
$XDG_CONFIG_HOME/powersync/config.yaml
194
+
# or, when XDG_CONFIG_HOME is not set:
195
+
~/.config/powersync/config.yaml
196
+
```
197
+
198
+
If you decline this prompt, login exits without storing a token. Use `TOKEN` in that case.
199
+
200
+
`powersync logout` removes the stored token from whichever backend is active (secure storage or config-file fallback).
188
201
189
202
# Supplying Linking Information for Cloud and Self-Hosted Commands
`Not logged in. Run ${ux.colorize('blue','powersync login')} to authenticate (you will be prompted for your token). Login is supported on macOS (other platforms coming soon), or provide the ${ux.colorize('blue','TOKEN')} environment variable.`
27
+
`Not logged in. Run ${ux.colorize('blue','powersync login')} to authenticate (you will be prompted for your token), or provide the ${ux.colorize('blue','TOKEN')} environment variable.`
`Not logged in. Run ${ux.colorize('blue','powersync login')} to authenticate (you will be prompted for your token). Login is supported on macOS (other platforms coming soon), or provide the ${ux.colorize('blue','TOKEN')} environment variable.`
68
+
`Not logged in. Run ${ux.colorize('blue','powersync login')} to authenticate (you will be prompted for your token), or provide the ${ux.colorize('blue','TOKEN')} environment variable.`
0 commit comments