@dinoxx/dinox-cli 2.8.1 → 2.10.0

package/README.md

@@ -113,42 +113,38 @@ dino update
 
 ### 第 1 步：登录
 
+在自己的终端运行：
+
 ```bash
-read -rs DINOX_TOKEN
-printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
-unset DINOX_TOKEN
+dino auth login
 ```
 
-说明：
-
-- 第一行会在当前终端隐藏输入 token，避免 token 出现在命令参数和 shell 历史中
-- `--token-stdin` 接受 token 本体或 `Bearer ...`
-- 登录时 CLI 会顺便验证连接是否可用
-- 自动化或 CI 可以改用 `DINOX_TOKEN` 环境变量注入 token；它优先于本地配置，并支持 token 本体或 `Bearer ...`
+终端会显示二维码。用 Dinox App 打开 **设置 → 设备配对 → 扫一扫**，扫码确认即可。登录时会完成首次同步，之后的读取命令会自动启动本地 daemon，一般不用再手动执行 `dino sync` 或 `dino auth status`。
 
-### 第 2 步：同步数据到本地
+如果 App 提示二维码无效，先升级 Dinox App。这条命令最长等待 10 分钟。
 
-```bash
-dino sync
-```
+#### CI / 自动化
 
-这一步会把 Dinox 数据同步到本地 SQLite 数据库，后续很多查询都会直接使用本地缓存。
-
-### 第 3 步：确认当前状态
+没有人可以扫码时，继续用 token。token 可在 App 的 **设置 → 同步设置 → API Token** 获取。
 
 ```bash
-dino auth status
+read -rs DINOX_TOKEN
+printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
+unset DINOX_TOKEN
 ```
 
-你会看到当前是否已登录、本地数据库位置、最近同步状态等信息。
+说明：
+
+- `--token-stdin` 接受 token 本体或 `Bearer ...`
+- 也可以只在当前进程注入 `DINOX_TOKEN`（优先于本地配置，支持 token 本体或 `Bearer ...`），不写入配置文件
 
-### 第 4 步：搜索一条笔记试试
+### 第 2 步：搜索一条笔记试试
 
 ```bash
 dino note search "AI"
 ```
 
-### 第 5 步：新建一条笔记试试
+### 第 3 步：新建一条笔记试试
 
 ```bash
 dino note create \
@@ -157,7 +153,7 @@ dino note create \
   --type note
 ```
 
-如果你能顺利完成上面 5 步，说明 CLI 已经可以正常使用。
+如果你能顺利完成上面 3 步，说明 CLI 已经可以正常使用。
 
 ---
 
@@ -692,6 +688,7 @@ dino note search "AI" --offline --format json
 ### 6.2 `auth`：登录与状态
 
 ```bash
+dino auth login
 read -rs DINOX_TOKEN
 printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
 unset DINOX_TOKEN
@@ -702,7 +699,8 @@ dino auth logout --clear-local-db
 
 用途说明：
 
-- `login`：保存 token 并验证连接
+- `login`：不带 token 时在终端显示二维码，用 Dinox App「设置 → 设备配对 → 扫一扫」确认登录；也可以保存 token 并验证连接
+- 登录会完成首次同步。CI / 自动化没有扫码条件时，用 `--token-stdin` 或 `DINOX_TOKEN`
 - `status`：查看登录状态、本地库位置、同步状态
 - `logout`：退出登录
 - `logout --clear-local-db`：退出并删除本地 SQLite 缓存
@@ -1008,13 +1006,12 @@ schema 包含命令路径、风险级别、参数、选项、输出字段和示
 
 原因：你还没有完成登录，或当前 `DINOX_TOKEN` 环境变量覆盖了本地 token，CLI 需要先在线解析这个 token 对应的用户身份。
 
-解决：
+解决：在自己的终端运行 `dino auth login`，用 Dinox App 扫码。CI 或已有 token 时：
 
 ```bash
 read -rs DINOX_TOKEN
 printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
 unset DINOX_TOKEN
-dino sync
 ```
 
 如果你使用环境变量登录，确认 `DINOX_TOKEN` 已设置后直接运行一次在线命令：
@@ -1135,6 +1132,7 @@ dino schema todo.update --format json
 | `DINOX_DATA_DIR` | 覆盖本地数据目录 |
 | `DINOX_TOKEN` | 用环境变量注入登录 token，优先级高于本地配置；可传 token 本体或 `Bearer ...` |
 | `DINOX_SYNC_TIMEOUT_MS` | 覆盖同步超时 |
+| `DINOX_DAEMON_AUTO_INSTALL` | 设为 `0` 时，`auth login` / `gateway add` 不再自动把 daemon 安装为登录服务 |
 
 ### 9.3 macOS / Linux 与 Windows 的多行命令差异
 
@@ -1192,11 +1190,10 @@ dino schema <path> --format json
 如果你是第一次用，建议按下面顺序熟悉：
 
 1. `dino auth login`
-2. `dino sync`
-3. `dino note search`
-4. `dino note create`
-5. `dino todo search`
-6. `dino tag add` / `dino box add`
-7. `dino schema`
+2. `dino note search`
+3. `dino note create`
+4. `dino todo search`
+5. `dino tag add` / `dino box add`
+6. `dino schema`
 
 这样会最快建立完整使用感。

package/dist/auth/devicePair.d.ts

@@ -0,0 +1,62 @@
+import type { DinoxConfig } from '../config/types.js';
+export declare const CLI_DEVICE_TYPE = "cli";
+export declare const DEVICE_PAIR_POLL_INTERVAL_MS = 2000;
+export declare const DEVICE_PAIR_MAX_WAIT_MS: number;
+export declare class DevicePairCancelled extends Error {
+    constructor();
+}
+export type DevicePairConfigStore = {
+    load: () => Promise<DinoxConfig>;
+    update: (update: (current: DinoxConfig) => DinoxConfig | Promise<DinoxConfig>) => Promise<DinoxConfig>;
+};
+type FetchLike = typeof fetch;
+export declare function deviceNameFromHostname(hostname: string): string;
+export declare function buildDevicePairQrUrl(ticket: string, deviceName: string): string;
+/** Origin of the configured PowerSync token endpoint. Pairing routes live on that same host. */
+export declare function authApiBaseFromTokenEndpoint(tokenEndpoint: string): string;
+export declare function renderTerminalQr(url: string): Promise<string>;
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function ensureCliDeviceId(store: DevicePairConfigStore, randomUUID: () => string): Promise<string>;
+export declare function revokeDeviceBinding(input: {
+    apiBase: string;
+    deviceBindingId: string;
+    authorization: string;
+    fetchImpl?: FetchLike;
+}): Promise<{
+    revoked: boolean;
+    warning?: string;
+}>;
+export declare function prepareCliDevice(input: {
+    store: DevicePairConfigStore;
+    apiBase: string;
+    authorization?: string;
+    deviceBindingId?: string;
+    fetchImpl?: FetchLike;
+    randomUUID: () => string;
+}): Promise<{
+    deviceId: string;
+    revokeWarning?: string;
+}>;
+export declare function saveDevicePairResult(input: {
+    store: DevicePairConfigStore;
+    deviceBindingId: string;
+}): Promise<void>;
+export type DevicePairLoginResult = {
+    token: string;
+    deviceBindingId?: string;
+    userNo?: string;
+};
+export declare function pollDevicePairLogin(input: {
+    apiBase: string;
+    deviceId: string;
+    deviceName: string;
+    fetchImpl?: FetchLike;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    renderQr?: (url: string) => Promise<string>;
+    writeStderr?: (text: string) => void;
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+    maxWaitMs?: number;
+}): Promise<DevicePairLoginResult>;
+export {};

package/dist/auth/devicePair.js

@@ -0,0 +1,377 @@
+import { toString as qrCodeToString } from 'qrcode';
+import { DinoxError } from '../utils/errors.js';
+import { toAuthorizationHeaderValue } from '../utils/authToken.js';
+export const CLI_DEVICE_TYPE = 'cli';
+export const DEVICE_PAIR_POLL_INTERVAL_MS = 2_000;
+export const DEVICE_PAIR_MAX_WAIT_MS = 10 * 60 * 1000;
+const DEVICE_PAIR_REQUEST_TIMEOUT_MS = 15_000;
+const AUTH_CODE_OK = '000000';
+const AUTH_CODE_INVALID = '000001';
+const AUTH_CODE_EXPIRED = '000002';
+const AUTH_CODE_PENDING = '000003';
+const AUTH_CODE_BOUND_ELSEWHERE = '000004';
+const TOKEN_LOGIN_HINT = 'printf \'%s\' "$TOKEN" | dino auth login --token-stdin';
+export class DevicePairCancelled extends Error {
+    constructor() {
+        super('Device pairing cancelled');
+        this.name = 'DevicePairCancelled';
+    }
+}
+export function deviceNameFromHostname(hostname) {
+    const stripped = hostname.replace(/\.local$/i, '').trim();
+    return stripped || 'Dinox CLI';
+}
+export function buildDevicePairQrUrl(ticket, deviceName) {
+    return `dinoxapp://device-pair?t=${encodeURIComponent(ticket)}&dt=${CLI_DEVICE_TYPE}&dn=${encodeURIComponent(deviceName)}`;
+}
+/** Origin of the configured PowerSync token endpoint. Pairing routes live on that same host. */
+export function authApiBaseFromTokenEndpoint(tokenEndpoint) {
+    try {
+        return new URL(tokenEndpoint).origin;
+    }
+    catch (error) {
+        throw new DinoxError(`Invalid token endpoint: ${tokenEndpoint}`, {
+            code: 'COMMAND_FAILED',
+            cause: error,
+        });
+    }
+}
+export function renderTerminalQr(url) {
+    return new Promise((resolve, reject) => {
+        qrCodeToString(url, { type: 'terminal', small: true }, (error, qr) => {
+            if (error)
+                reject(error);
+            else
+                resolve(qr);
+        });
+    });
+}
+export function delay(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(new DevicePairCancelled());
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(finish, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new DevicePairCancelled());
+        };
+        function finish() {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export async function ensureCliDeviceId(store, randomUUID) {
+    const current = await store.load();
+    const existing = current.auth?.deviceId?.trim();
+    if (existing?.startsWith(`${CLI_DEVICE_TYPE}-`))
+        return existing;
+    const deviceId = `${CLI_DEVICE_TYPE}-${randomUUID()}`;
+    await store.update((config) => ({
+        ...config,
+        auth: {
+            ...(config.auth ?? {}),
+            deviceId,
+        },
+    }));
+    return deviceId;
+}
+export async function revokeDeviceBinding(input) {
+    const endpoint = `${input.apiBase}/auth/device/revoke`;
+    try {
+        const result = await postDeviceApi({
+            fetchImpl: input.fetchImpl ?? fetch,
+            url: endpoint,
+            body: { id: input.deviceBindingId },
+            authorization: input.authorization,
+        });
+        if (!result.ok) {
+            return { revoked: false, warning: revokeWarning(input.deviceBindingId, errorText(result.error)) };
+        }
+        if (result.code !== AUTH_CODE_OK) {
+            return {
+                revoked: false,
+                warning: revokeWarning(input.deviceBindingId, `${result.code} ${result.msg}`.trim()),
+            };
+        }
+        return { revoked: true };
+    }
+    catch (error) {
+        if (error instanceof DevicePairCancelled)
+            throw error;
+        return { revoked: false, warning: revokeWarning(input.deviceBindingId, errorText(error)) };
+    }
+}
+function revokeWarning(deviceBindingId, detail) {
+    return `warning: could not revoke paired device ${deviceBindingId} (${detail}). Continuing.`;
+}
+export async function prepareCliDevice(input) {
+    let revokeWarning;
+    let bindingReleased = true;
+    const bindingId = input.deviceBindingId?.trim();
+    if (bindingId) {
+        bindingReleased = false;
+        if (!input.authorization) {
+            revokeWarning = `warning: could not revoke paired device ${bindingId} (no saved token). Continuing.`;
+        }
+        else {
+            const revoked = await revokeDeviceBinding({
+                apiBase: input.apiBase,
+                deviceBindingId: bindingId,
+                authorization: input.authorization,
+                fetchImpl: input.fetchImpl,
+            });
+            if (revoked.revoked) {
+                bindingReleased = true;
+                await input.store.update((config) => ({
+                    ...config,
+                    auth: {
+                        ...(config.auth ?? {}),
+                        deviceBindingId: undefined,
+                    },
+                }));
+            }
+            else {
+                revokeWarning = revoked.warning;
+            }
+        }
+    }
+    // The server refuses a device id still actively bound to another account
+    // (000004, shown on the phone, never to the polling CLI). A released binding
+    // lets any account reuse the id; one that could not be released gets a fresh
+    // id before pairing, so switching accounts cannot hit that refusal.
+    if (!bindingReleased) {
+        const deviceId = `${CLI_DEVICE_TYPE}-${input.randomUUID()}`;
+        await input.store.update((config) => ({
+            ...config,
+            auth: { ...(config.auth ?? {}), deviceId, deviceBindingId: undefined },
+        }));
+        return { deviceId, revokeWarning };
+    }
+    const deviceId = await ensureCliDeviceId(input.store, input.randomUUID);
+    return { deviceId, revokeWarning };
+}
+export async function saveDevicePairResult(input) {
+    await input.store.update((config) => ({
+        ...config,
+        auth: { ...(config.auth ?? {}), deviceBindingId: input.deviceBindingId },
+    }));
+}
+export async function pollDevicePairLogin(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const sleep = input.sleep ?? ((ms) => delay(ms, input.signal));
+    const now = input.now ?? (() => Date.now());
+    const renderQr = input.renderQr ?? renderTerminalQr;
+    const writeStderr = input.writeStderr ?? ((text) => { process.stderr.write(text); });
+    const pollIntervalMs = input.pollIntervalMs ?? DEVICE_PAIR_POLL_INTERVAL_MS;
+    const deadline = now() + (input.maxWaitMs ?? DEVICE_PAIR_MAX_WAIT_MS);
+    // Expiry is the server's call (000002): its `expireAt` has no time zone, so a
+    // local comparison would misjudge it on any machine in another zone.
+    let ticket = null;
+    let shownTicket = null;
+    const waitForNextPoll = async () => {
+        throwIfCancelled(input.signal);
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            return;
+        await sleep(Math.min(pollIntervalMs, remaining));
+        throwIfCancelled(input.signal);
+    };
+    const issueTicket = async () => {
+        const generated = await postDeviceApi({
+            fetchImpl,
+            url: `${input.apiBase}/auth/device/pair/qr/generate`,
+            body: { deviceId: input.deviceId },
+            signal: input.signal,
+        });
+        if (!generated.ok)
+            return false;
+        if (generated.code !== AUTH_CODE_OK) {
+            throw pairingBusinessError(generated.code, generated.msg);
+        }
+        const data = asRecord(generated.data);
+        const nextTicket = readString(data?.ticket);
+        if (!nextTicket) {
+            throw new DinoxError('Device pairing ticket response did not include a ticket.', {
+                code: 'AUTH_PAIRING_FAILED',
+                details: { backendCode: generated.code, backendMessage: generated.msg },
+            });
+        }
+        ticket = nextTicket;
+        // The server hands back the same ticket while it is still valid; reprint only a new one.
+        if (nextTicket !== shownTicket) {
+            shownTicket = nextTicket;
+            await showPairingQr({ ticket: nextTicket, deviceName: input.deviceName, renderQr, writeStderr });
+        }
+        return true;
+    };
+    while (now() < deadline) {
+        throwIfCancelled(input.signal);
+        if (!ticket) {
+            try {
+                const issued = await issueTicket();
+                if (!issued) {
+                    await waitForNextPoll();
+                    continue;
+                }
+            }
+            catch (error) {
+                if (error instanceof DinoxError || error instanceof DevicePairCancelled)
+                    throw error;
+                await waitForNextPoll();
+                continue;
+            }
+        }
+        if (!ticket)
+            continue;
+        let polled;
+        try {
+            polled = await postDeviceApi({
+                fetchImpl,
+                url: `${input.apiBase}/auth/device/pair/qr/token`,
+                body: {
+                    deviceId: input.deviceId,
+                    ticket,
+                    deviceType: CLI_DEVICE_TYPE,
+                    deviceName: input.deviceName,
+                },
+                signal: input.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof DevicePairCancelled)
+                throw error;
+            await waitForNextPoll();
+            continue;
+        }
+        if (!polled.ok) {
+            await waitForNextPoll();
+            continue;
+        }
+        if (polled.code === AUTH_CODE_OK) {
+            return readPairToken(polled.data, polled.code, polled.msg);
+        }
+        if (polled.code === AUTH_CODE_PENDING) {
+            await waitForNextPoll();
+            continue;
+        }
+        if (polled.code === AUTH_CODE_EXPIRED) {
+            ticket = null;
+            await waitForNextPoll();
+            continue;
+        }
+        throw pairingBusinessError(polled.code, polled.msg);
+    }
+    throw new DinoxError('Timed out waiting for the Dinox app to approve this device.', {
+        code: 'AUTH_PAIRING_TIMEOUT',
+        suggestion: 'Run `dino auth login` again and approve the QR code within 10 minutes.',
+    });
+}
+async function showPairingQr(input) {
+    const url = buildDevicePairQrUrl(input.ticket, input.deviceName);
+    const rendered = await input.renderQr(url);
+    input.writeStderr(rendered.endsWith('\n') ? rendered : `${rendered}\n`);
+    input.writeStderr('用 Dinox App 扫码：设置 → 设备配对 → 扫一扫\n');
+    input.writeStderr(`${url}\n`);
+    input.writeStderr(`App 提示二维码无效？请先升级 Dinox App，或改用 token 登录：\`${TOKEN_LOGIN_HINT}\`\n`);
+}
+function pairingBusinessError(code, msg) {
+    if (code === AUTH_CODE_INVALID && isUnsupportedDeviceType(msg)) {
+        return new DinoxError('This server does not support CLI device pairing yet (deviceType is not allowed).', {
+            code: 'AUTH_PAIRING_UNSUPPORTED',
+            details: { backendCode: code, backendMessage: msg },
+            suggestion: 'The Dinox server does not accept CLI QR login yet. Log in with a token via `dino auth login --token-stdin` for now.',
+            suggestedAction: {
+                command: 'dino auth login --token-stdin',
+                reason: 'The server rejected deviceType cli. Use token login until CLI pairing is enabled.',
+            },
+        });
+    }
+    const boundElsewhere = code === AUTH_CODE_BOUND_ELSEWHERE;
+    return new DinoxError(`Device pairing failed (${code}): ${msg || 'unknown error'}`, {
+        code: 'AUTH_PAIRING_FAILED',
+        details: { backendCode: code, backendMessage: msg },
+        suggestion: boundElsewhere
+            ? 'Remove this computer from the original account in the Dinox app under 我的设备, then run `dino auth login` again.'
+            : 'Retry `dino auth login`, or log in with a token via `dino auth login --token-stdin`.',
+    });
+}
+function isUnsupportedDeviceType(msg) {
+    return /deviceType/i.test(msg) && /不合法|invalid|illegal|unsupported/i.test(msg);
+}
+function readPairToken(data, code, msg) {
+    const record = asRecord(data);
+    const token = readString(record?.token);
+    if (!token) {
+        throw new DinoxError('Device pairing succeeded but did not return a token.', {
+            code: 'AUTH_PAIRING_FAILED',
+            details: { backendCode: code, backendMessage: msg },
+        });
+    }
+    return {
+        token,
+        deviceBindingId: readString(record?.deviceBindingId),
+        userNo: readString(record?.userNo),
+    };
+}
+async function postDeviceApi(input) {
+    throwIfCancelled(input.signal);
+    const timeout = AbortSignal.timeout(DEVICE_PAIR_REQUEST_TIMEOUT_MS);
+    const signal = input.signal ? AbortSignal.any([input.signal, timeout]) : timeout;
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (input.authorization)
+            headers.Authorization = toAuthorizationHeaderValue(input.authorization);
+        const response = await input.fetchImpl(input.url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(input.body),
+            signal,
+        });
+        throwIfCancelled(input.signal);
+        const text = await response.text();
+        let payload;
+        try {
+            payload = text ? JSON.parse(text) : null;
+        }
+        catch (error) {
+            return { ok: false, error };
+        }
+        const record = asRecord(payload);
+        if (!record || record.code === undefined || record.code === null) {
+            return { ok: false, error: new Error(response.ok ? 'missing response code' : `HTTP ${response.status}`) };
+        }
+        return {
+            ok: true,
+            code: String(record.code),
+            msg: typeof record.msg === 'string' ? record.msg : '',
+            data: record.data,
+        };
+    }
+    catch (error) {
+        if (input.signal?.aborted || error instanceof DevicePairCancelled)
+            throw new DevicePairCancelled();
+        return { ok: false, error };
+    }
+}
+function throwIfCancelled(signal) {
+    if (signal?.aborted)
+        throw new DevicePairCancelled();
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function readString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/commands/auth/index.js

@@ -1,4 +1,7 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
+import os from 'node:os';
+import { authApiBaseFromTokenEndpoint, DevicePairCancelled, deviceNameFromHostname, pollDevicePairLogin, prepareCliDevice, renderTerminalQr, revokeDeviceBinding, saveDevicePairResult, } from '../../auth/devicePair.js';
 import { buildPendingAuthConfig, fetchUserInfoWithAuthorization, hydrateResolvedAuthIdentity, mergeAuthIdentityIntoConfig, persistedAuthStateMatches, rotatePersistedAuthStateRevision, } from '../../auth/userInfo.js';
 import { getLegacyPowerSyncDbPath, getPowerSyncDbPath } from '../../config/paths.js';
 import { loadConfig, updateConfig } from '../../config/store.js';
@@ -6,6 +9,7 @@ import { resolveConfig } from '../../config/resolve.js';
 import { getDaemonInfo } from '../../daemon/client.js';
 import { restoreSuspendedDaemonLocked, suspendDaemonForExclusiveAccessLocked, } from '../../daemon/lifecycle.js';
 import { stopDaemonLocked } from '../../daemon/index.js';
+import { autoInstallDaemonService, describeDaemonServiceAutoInstall } from '../../daemon/autoInstall.js';
 import { acquireDaemonStartLock } from '../../daemon/pid.js';
 import { fetchCredentialsWithAuthorization } from '../../powersync/connector.js';
 import { withExclusivePowerSync } from '../../powersync/exclusiveRuntime.js';
@@ -226,6 +230,45 @@ export async function performAuthLogin(rawToken, syncTimeout, overrides = {}) {
     }
     return outcome.value;
 }
+async function loginWithDeviceQr() {
+    const config = await loadConfig();
+    const resolved = resolveConfig(config);
+    const apiBase = authApiBaseFromTokenEndpoint(resolved.powersync.tokenEndpoint);
+    const store = { load: loadConfig, update: updateConfig };
+    const prepared = await prepareCliDevice({
+        store,
+        apiBase,
+        authorization: normalizeAuthToken(config.auth?.authorization),
+        deviceBindingId: config.auth?.deviceBindingId,
+        randomUUID: crypto.randomUUID,
+    });
+    if (prepared.revokeWarning)
+        printHumanReadableWarning(prepared.revokeWarning);
+    const abort = new AbortController();
+    const onSigint = () => abort.abort();
+    process.once('SIGINT', onSigint);
+    try {
+        const paired = await pollDevicePairLogin({
+            apiBase,
+            deviceId: prepared.deviceId,
+            deviceName: deviceNameFromHostname(os.hostname()),
+            renderQr: renderTerminalQr,
+            writeStderr: (text) => { process.stderr.write(text); },
+            signal: abort.signal,
+        });
+        return { token: paired.token, deviceBindingId: paired.deviceBindingId };
+    }
+    catch (error) {
+        if (error instanceof DevicePairCancelled) {
+            process.exitCode = 130;
+            process.exit(130);
+        }
+        throw error;
+    }
+    finally {
+        process.off('SIGINT', onSigint);
+    }
+}
 async function runAuthLogin(context) {
     const options = context.options;
     if (context.args.token && options.tokenStdin) {
@@ -233,19 +276,39 @@ async function runAuthLogin(context) {
             code: 'USAGE_ERROR',
         });
     }
-    const token = options.tokenStdin ? await readAuthTokenFromStdin() : context.args.token;
-    const rawToken = normalizeAuthToken(token);
-    if (!rawToken) {
-        throw new DinoxError('Token is required');
-    }
+    const explicitToken = options.tokenStdin ? await readAuthTokenFromStdin() : context.args.token;
+    let rawToken = normalizeAuthToken(explicitToken);
+    let pairedDeviceBindingId;
     const envToken = readEnvAuthToken();
+    if (options.tokenStdin || context.args.token) {
+        if (!rawToken) {
+            throw new DinoxError('Token is required');
+        }
+    }
+    else {
+        // A scanned login can never equal DINOX_TOKEN, so refuse before the phone binds this computer.
+        if (envToken) {
+            throw new DinoxError('DINOX_TOKEN is set, so a QR login would be overridden by it. Unset DINOX_TOKEN before running `dino auth login`, or log in with that token via `--token-stdin`.', { code: 'USAGE_ERROR' });
+        }
+        const paired = await loginWithDeviceQr();
+        rawToken = paired.token;
+        pairedDeviceBindingId = paired.deviceBindingId;
+    }
     if (envToken && envToken !== rawToken) {
         throw new DinoxError('DINOX_TOKEN is set and differs from the login token. Unset DINOX_TOKEN before running `dino auth login`, or use the same token.');
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
     const result = await performAuthLogin(rawToken, context.globals.syncTimeout);
+    if (pairedDeviceBindingId) {
+        await saveDevicePairResult({
+            store: { load: loadConfig, update: updateConfig },
+            deviceBindingId: pairedDeviceBindingId,
+        });
+    }
+    // After the login lock is released: the service starts the daemon under the new login.
+    const daemonService = await autoInstallDaemonService();
     if (structuredOutput) {
-        printSuccess(result);
+        printSuccess({ ...result, daemonService });
         return;
     }
     printHumanReadableLine('Login verified.');
@@ -258,11 +321,30 @@ async function runAuthLogin(context) {
     if (result.stale) {
         printHumanReadableLine('- warning: initial sync timed out; local cache may be stale');
     }
+    const serviceNote = describeDaemonServiceAutoInstall(daemonService);
+    if (serviceNote)
+        printHumanReadableWarning(serviceNote);
 }
 async function runAuthLogoutLocked(options) {
     const config = await loadConfig();
     const resolved = resolveConfig(config);
     const envTokenActive = Boolean(readEnvAuthToken());
+    const savedToken = normalizeAuthToken(config.auth?.authorization);
+    const deviceBindingId = config.auth?.deviceBindingId?.trim();
+    if (deviceBindingId) {
+        if (!savedToken) {
+            printHumanReadableWarning(`warning: could not revoke paired device ${deviceBindingId} (no saved token). Continuing.`);
+        }
+        else {
+            const revoked = await revokeDeviceBinding({
+                apiBase: authApiBaseFromTokenEndpoint(resolved.powersync.tokenEndpoint),
+                deviceBindingId,
+                authorization: savedToken,
+            });
+            if (revoked.warning)
+                printHumanReadableWarning(revoked.warning);
+        }
+    }
     const daemonInfo = await getDaemonInfo();
     let initiallyResolvedUserId = resolved.auth.userId;
     if (!initiallyResolvedUserId
@@ -334,6 +416,8 @@ async function runAuthLogoutLocked(options) {
                     username: undefined,
                     email: undefined,
                     userInfoSyncedAt: undefined,
+                    deviceBindingId: undefined,
+                    deviceId: undefined,
                 },
             });
         }, { timeoutMs: resolved.sync.timeoutMs });
@@ -483,8 +567,8 @@ export const authCommandGroup = {
     commands: [
         {
             name: 'login',
-            description: 'Save login token and verify PowerSync connectivity',
-            arguments: [{ syntax: '[token]', description: 'Login token (omit when using --token-stdin)' }],
+            description: 'Log in by scanning a QR code, or save a token and verify PowerSync connectivity',
+            arguments: [{ syntax: '[token]', description: 'Login token (omit to scan a QR code, or when using --token-stdin)' }],
             options: [{ flags: '--token-stdin', description: 'Read the login token from piped stdin instead of argv', type: 'boolean' }],
             schema: {
                 path: 'auth.login',
@@ -494,9 +578,13 @@ export const authCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Login verification result',
-                    fields: ['verified', 'endpoint', 'dbPath', 'stale', 'lastSyncedAt', 'userId'],
+                    fields: ['verified', 'endpoint', 'dbPath', 'stale', 'lastSyncedAt', 'userId', 'daemonService'],
                 },
-                examples: ['dino auth login --token-stdin --format json'],
+                examples: [
+                    'dino auth login',
+                    'dino auth login --format json',
+                    'dino auth login --token-stdin --format json',
+                ],
             },
             action: runAuthLogin,
         },

package/dist/commands/gateway/index.js

@@ -1,6 +1,7 @@
 import { getDaemonInfo, isDaemonRunning, sendDaemonRequest } from '../../daemon/client.js';
 import { getDaemonService } from '../../daemon/supervisor.js';
 import { ensureDaemonRunning } from '../../daemon/ensure.js';
+import { autoInstallDaemonService, describeDaemonServiceAutoInstall } from '../../daemon/autoInstall.js';
 import { loadConfig } from '../../config/store.js';
 import { addGateway, adoptDetectedAgent, getGatewaysFilePath, loadGateways, removeGateway, } from '../../gateway/config.js';
 import { detectAcpAgents, inferAgentId } from '../../gateway/detect.js';
@@ -56,8 +57,17 @@ async function warnIfDaemonUnmanaged() {
         printHumanReadableWarning('warning: gateways run in a daemon owned by the shell or agent session that started it, and go offline when that session ends. Run `dino daemon install` to keep them online.');
     }
 }
-/** Applies the account's gateways to the running daemon, starting it when needed. */
-async function applyToDaemon() {
+/**
+ * Applies the account's gateways to the running daemon, starting it when needed.
+ * `keepOnline` first hands the daemon to the login service (once), so a gateway
+ * added from an agent session does not go offline when that session ends.
+ */
+async function applyToDaemon(options = {}) {
+    if (options.keepOnline) {
+        const note = describeDaemonServiceAutoInstall(await autoInstallDaemonService());
+        if (note)
+            printHumanReadableWarning(note);
+    }
     let gateways;
     if (!(await isDaemonRunning())) {
         await ensureDaemonRunning();
@@ -98,7 +108,7 @@ async function runAdd(context) {
         cwd: context.options.cwd,
         env: parseEnv(context.options.env),
     });
-    const statuses = await applyToDaemon();
+    const statuses = await applyToDaemon({ keepOnline: true });
     if (getRequestedStructuredOutputFormat()) {
         printSuccess({ gateway: describeGateway(gateway), status: statuses.find((item) => item.gatewayId === gateway.id) ?? null });
         return;
@@ -122,7 +132,7 @@ async function runDetect(context) {
                 updated.push(result.gateway);
         }
     }
-    const statuses = added.length || updated.length ? await applyToDaemon() : [];
+    const statuses = added.length || updated.length ? await applyToDaemon({ keepOnline: true }) : [];
     if (getRequestedStructuredOutputFormat()) {
         printSuccess({
             agents: detected,

package/dist/commands/graph/index.js

@@ -48,6 +48,8 @@ async function runGraphCommand(context, onlineAction, offlineAction) {
         });
     }
     catch (error) {
+        if (error instanceof DinoxError && error.code === 'AUTH_REQUIRED')
+            throw error;
         const message = error instanceof Error ? error.message : String(error);
         throw new DinoxError(`Daemon execution failed: ${message}`, {
             code: 'DAEMON_UNAVAILABLE',

package/dist/commands/schema/renderSkills.js

@@ -242,7 +242,7 @@ export function renderBundledSkillReference() {
         lines.push('```');
         lines.push('');
         if (section.title === 'Auth') {
-            lines.push('Agent safety: the positional login-token form is legacy compatibility and is intentionally omitted from this agent-facing signature. Agent workflows must never place a Dinox authentication token in argv; use `--token-stdin` from the user\'s own shell or secret store.');
+            lines.push('Agent safety: the positional login-token form is legacy compatibility and is intentionally omitted from this agent-facing signature. Agent workflows must never place a Dinox authentication token in argv. Prefer `dino auth login` in the user\'s terminal (QR code; it blocks for up to 10 minutes; in Claude Code the user can type `! dino auth login`). Use `--token-stdin` only from the user\'s own shell or secret store.');
             lines.push('');
         }
     }
@@ -287,7 +287,7 @@ export function renderPortableRuntimeContract() {
         '- On a nonzero exit, parse structured stderr. Use top-level `code`, `recoverable`, `exit_code`, and `suggested_action`; inspect `error` for details. `dino schema errors --format json` lists every code and its exit status.',
         '- A direct user request for an exact write authorizes that write when the dry-run matches. Ask again before delete, overwrite, merge, bulk mutation, local-cache removal, repair, global CLI update, or whenever targets or impact are ambiguous.',
         '- A dry-run does not apply the planned mutation, but an online PowerSync runtime may flush older queued writes. Use `--offline` only when the user accepts stale local-cache semantics.',
-        '- Do not ask for Dinox authentication credentials in chat or place a Dinox authentication token in argv. The `dino` child process must inherit `DINOX_TOKEN` or receive it from the host secret store at execution time; if the host cannot inject it safely, have the user perform persistent `--token-stdin` login in their own terminal.',
+        '- Do not ask for Dinox authentication credentials in chat or place a Dinox authentication token in argv. For persistent login, have the user run `dino auth login` in their own terminal and scan the QR code with the Dinox app. In Claude Code they can type `! dino auth login`. That command blocks for up to 10 minutes; say so before an agent runs it. Inherited `DINOX_TOKEN` and `dino auth login --token-stdin` remain for CI and secret stores.',
         '- Execute `dino` in an environment that can access the intended CLI binary, Dinox config/cache, and injected secret. Host-turn secret injection does not automatically cross into a sandbox or remote execution backend; never copy a secret through prompts to bridge that boundary.',
         '- If the host times out before receiving a structured envelope, treat the outcome as unknown. Verify freshness or the write postcondition before retrying.',
         '- Before claiming complete, current, all, none, latest, or an exact count, verify the command\'s freshness field is false (usually `data.stale`; note search uses `data.meta.stale`), inspect `_notice`, and check pagination or truncation fields returned by the command.',

package/dist/config/types.d.ts

@@ -13,6 +13,10 @@ export type DinoxConfig = {
         userInfoSyncedAt?: string;
         /** Internal CAS token changed by every persisted login/logout transition. */
         stateRevision?: string;
+        /** Stable id for QR login (`cli-` + uuid). Reused for the same account on this machine. */
+        deviceId?: string;
+        /** `c_user_device.id` from the last successful QR login. */
+        deviceBindingId?: string;
     };
     powersync?: {
         /** PowerSync sync service endpoint (downloads/subscriptions). */

package/dist/daemon/autoInstall.d.ts

@@ -0,0 +1,32 @@
+import type { DinoxConfig } from '../config/types.js';
+import { type DaemonService, type DaemonServiceKind } from './supervisor.js';
+/** `0` / `false` / `off` / `no` keeps the CLI from installing the daemon service on its own. */
+export declare const DAEMON_AUTO_INSTALL_ENV = "DINOX_DAEMON_AUTO_INSTALL";
+export type DaemonServiceAutoInstallSkipReason = 'disabled' | 'ci' | 'custom-data-dir' | 'unsupported' | 'no-login' | 'env-token';
+export type DaemonServiceAutoInstallResult = {
+    status: 'installed' | 'already-installed' | 'skipped' | 'failed';
+    service: DaemonServiceKind | null;
+    reason: DaemonServiceAutoInstallSkipReason | null;
+    error: string | null;
+};
+export type DaemonServiceAutoInstallDependencies = {
+    env: NodeJS.ProcessEnv;
+    getService: () => DaemonService | null;
+    loadConfig: () => Promise<DinoxConfig>;
+    install: () => Promise<unknown>;
+    /** Removes whatever a failed install left behind. */
+    rollback: () => Promise<unknown>;
+};
+/**
+ * Makes the daemon a login service without the user having to know it exists.
+ * Without one it belongs to whichever shell or agent session first started it
+ * and dies with that session. Called after `auth login` and when gateways are
+ * added; never throws, because neither of those should fail over it.
+ *
+ * Skipped where installing something that runs at login would surprise:
+ * an opt-out, CI, and custom data directories (tests, sandboxes, second
+ * profiles), which still get it from an explicit `dino daemon install`.
+ */
+export declare function autoInstallDaemonService(dependencies?: DaemonServiceAutoInstallDependencies): Promise<DaemonServiceAutoInstallResult>;
+/** One stderr line for a human caller; nothing when there is nothing to say. */
+export declare function describeDaemonServiceAutoInstall(result: DaemonServiceAutoInstallResult): string | null;

package/dist/daemon/autoInstall.js

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { loadConfig } from '../config/store.js';
+import { normalizeAuthToken } from '../utils/authToken.js';
+import { DinoxError } from '../utils/errors.js';
+import { installDaemonService, uninstallDaemonService } from './index.js';
+import { envTokenOverridesLogin } from './launch.js';
+import { getDaemonService } from './supervisor.js';
+/** `0` / `false` / `off` / `no` keeps the CLI from installing the daemon service on its own. */
+export const DAEMON_AUTO_INSTALL_ENV = 'DINOX_DAEMON_AUTO_INSTALL';
+/**
+ * systemd --user is missing in WSL without systemd, most containers, and
+ * other non-systemd distros; `/run/systemd/system` is how sd_booted() tells.
+ */
+function usableService() {
+    const service = getDaemonService();
+    if (service?.kind === 'systemd' && !existsSync('/run/systemd/system'))
+        return null;
+    return service;
+}
+const defaultDependencies = {
+    env: process.env,
+    getService: usableService,
+    loadConfig,
+    install: () => installDaemonService(),
+    rollback: () => uninstallDaemonService(),
+};
+function isFalsy(value) {
+    return ['0', 'false', 'off', 'no'].includes((value ?? '').trim().toLowerCase());
+}
+function isSet(value) {
+    return Boolean(value?.trim()) && !isFalsy(value);
+}
+function skipped(service, reason) {
+    return { status: 'skipped', service, reason, error: null };
+}
+/**
+ * Makes the daemon a login service without the user having to know it exists.
+ * Without one it belongs to whichever shell or agent session first started it
+ * and dies with that session. Called after `auth login` and when gateways are
+ * added; never throws, because neither of those should fail over it.
+ *
+ * Skipped where installing something that runs at login would surprise:
+ * an opt-out, CI, and custom data directories (tests, sandboxes, second
+ * profiles), which still get it from an explicit `dino daemon install`.
+ */
+export async function autoInstallDaemonService(dependencies = defaultDependencies) {
+    const { env } = dependencies;
+    if (isFalsy(env[DAEMON_AUTO_INSTALL_ENV]))
+        return skipped(null, 'disabled');
+    if (isSet(env.CI))
+        return skipped(null, 'ci');
+    if (env.DINOX_DATA_DIR)
+        return skipped(null, 'custom-data-dir');
+    const service = dependencies.getService();
+    if (!service)
+        return skipped(null, 'unsupported');
+    if (service.isInstalled()) {
+        return { status: 'already-installed', service: service.kind, reason: null, error: null };
+    }
+    let raw;
+    try {
+        raw = await dependencies.loadConfig();
+    }
+    catch (error) {
+        return { status: 'failed', service: service.kind, reason: null, error: errorMessage(error) };
+    }
+    if (!normalizeAuthToken(raw.auth?.authorization))
+        return skipped(service.kind, 'no-login');
+    if (envTokenOverridesLogin(raw, env))
+        return skipped(service.kind, 'env-token');
+    try {
+        await dependencies.install();
+        return { status: 'installed', service: service.kind, reason: null, error: null };
+    }
+    catch (error) {
+        // Every service writes its definition before asking the manager to load it,
+        // and the CLI starts the daemon through any definition it finds. Left in
+        // place after a failure (no GUI session over SSH, no user bus, a policy
+        // blocking Task Scheduler), it would break the on-demand start that worked
+        // before, so restore the state from before this attempt.
+        let message = errorMessage(error);
+        try {
+            await dependencies.rollback();
+        }
+        catch (rollbackError) {
+            message += `; cleanup also failed (${errorMessage(rollbackError)}), run \`dino daemon uninstall\``;
+        }
+        if (error instanceof DinoxError && error.code === 'DAEMON_SERVICE_UNSUPPORTED') {
+            return { status: 'skipped', service: service.kind, reason: 'unsupported', error: message };
+        }
+        return { status: 'failed', service: service.kind, reason: null, error: message };
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** One stderr line for a human caller; nothing when there is nothing to say. */
+export function describeDaemonServiceAutoInstall(result) {
+    if (result.status === 'installed') {
+        return `Background service installed (${result.service}): the daemon now starts at login and restarts after a crash. Remove it with \`dino daemon uninstall\`.`;
+    }
+    if (result.status === 'failed') {
+        return `warning: could not install the background service (${result.error}). The daemon still starts on demand; run \`dino daemon install\` to retry.`;
+    }
+    return null;
+}

package/dist/daemon/ensure.js

@@ -31,6 +31,13 @@ function matchesRuntimeTokenBinding(info, version, config) {
 async function ensureDaemonRunningUnlocked() {
     const expectedVersion = getPackageVersion();
     const baseConfig = resolveConfig(await loadConfig());
+    // A daemon cannot serve anything without a login; say so now instead of
+    // waiting for a launch that cannot become ready.
+    if (!baseConfig.auth.authorization) {
+        throw new DinoxError('Not logged in. Set DINOX_TOKEN or pipe a token to `dino auth login --token-stdin`.', {
+            code: 'AUTH_REQUIRED',
+        });
+    }
     const info = await getDaemonInfo();
     if (info && matchesRuntimeTokenBinding(info, expectedVersion, baseConfig)) {
         return;

package/dist/daemon/route.js

@@ -25,6 +25,8 @@ export async function routeRead(globals, daemonMethod, daemonParams, localRun) {
         return (await sendDaemonRequest(daemonMethod, daemonParams));
     }
     catch (error) {
+        if (error instanceof DinoxError && error.code === 'AUTH_REQUIRED')
+            throw error;
         const message = error instanceof Error ? error.message : String(error);
         throw new DinoxError(`Daemon execution failed: ${message}`, {
             code: 'DAEMON_UNAVAILABLE',

package/dist/utils/errorCodes.d.ts

@@ -11,6 +11,18 @@ export declare const ERROR_CODES: {
         readonly exitCode: 3;
         readonly description: "The configured credentials were rejected.";
     };
+    readonly AUTH_PAIRING_FAILED: {
+        readonly exitCode: 3;
+        readonly description: "Device QR login failed because the server rejected the pairing request.";
+    };
+    readonly AUTH_PAIRING_TIMEOUT: {
+        readonly exitCode: 3;
+        readonly description: "Device QR login timed out before the phone approved this computer.";
+    };
+    readonly AUTH_PAIRING_UNSUPPORTED: {
+        readonly exitCode: 3;
+        readonly description: "This server does not accept the CLI device type for QR login yet.";
+    };
     readonly AUTH_REQUIRED: {
         readonly exitCode: 3;
         readonly description: "The command needs an authenticated Dinox account.";

package/dist/utils/errorCodes.js

@@ -8,6 +8,9 @@
 export const ERROR_CODES = {
     ALREADY_EXISTS: { exitCode: 5, description: 'The target resource already exists.' },
     AUTH_INVALID: { exitCode: 3, description: 'The configured credentials were rejected.' },
+    AUTH_PAIRING_FAILED: { exitCode: 3, description: 'Device QR login failed because the server rejected the pairing request.' },
+    AUTH_PAIRING_TIMEOUT: { exitCode: 3, description: 'Device QR login timed out before the phone approved this computer.' },
+    AUTH_PAIRING_UNSUPPORTED: { exitCode: 3, description: 'This server does not accept the CLI device type for QR login yet.' },
     AUTH_REQUIRED: { exitCode: 3, description: 'The command needs an authenticated Dinox account.' },
     AUTH_STATE_CHANGED: { exitCode: 3, description: 'Authentication changed while the command was running.' },
     CACHE_CLEANUP_FAILED: { exitCode: 1, description: 'Local cache cleanup after logout did not complete.' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinoxx/dinox-cli",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "description": "Dinox CLI",
   "main": "dist/dinox.js",
   "scripts": {
@@ -78,6 +78,7 @@
     "@tiptap/markdown": "^3.20.0",
     "better-sqlite3": "^12.6.2",
     "commander": "^14.0.3",
+    "qrcode": "1.5.4",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
@@ -93,6 +94,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^20.19.0",
+    "@types/qrcode": "1.5.6",
     "eslint": "^10.12.0",
     "tsx": "^4.20.3",
     "typescript": "^5.9.3",