jackwener/OpenCLI · error · CliError

AUTH_REQUIRED

AUTH_REQUIRED

Error message

Not authenticated. Run: opencli spotify auth

What it means

getToken loads persisted tokens from disk and throws AUTH_REQUIRED when no token file exists at all. Spotify API calls require an access token, and the CLI will not silently start an auth flow, so it fails fast with the exact command needed to authenticate.

Source

Thrown at clis/spotify/spotify.js:70

        body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken }),
    });
    if (!res.ok) {
        const err = await res.json().catch(() => ({}));
        throw new CliError('REFRESH_FAILED', err?.error_description || `Token refresh failed (${res.status})`);
    }
    const data = await res.json();
    const tokens = {
        access_token: data.access_token,
        refresh_token: data.refresh_token || refreshToken,
        expires_at: Date.now() + data.expires_in * 1000,
    };
    saveTokens(tokens);
    return tokens.access_token;
}
async function getToken() {
    const tokens = loadTokens();
    if (!tokens)
        throw new CliError('AUTH_REQUIRED', 'Not authenticated. Run: opencli spotify auth');
    if (!tokens.access_token || !tokens.refresh_token || !(tokens.expires_at > 0)) {
        throw new CliError('AUTH_CORRUPTED', 'Token file is corrupted. Run: opencli spotify auth');
    }
    if (Date.now() > tokens.expires_at - 60_000)
        return refreshAccessToken(tokens.refresh_token);
    return tokens.access_token;
}
// ── Spotify API helper ────────────────────────────────────────────────────────
async function api(method, path, body) {
    const token = await getToken();
    const res = await fetch(`https://api.spotify.com/v1${path}`, {
        method,
        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
        body: body ? JSON.stringify(body) : undefined,
    });
    if (res.status === 204 || res.status === 202)
        return null;
    if (!res.ok) {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Run opencli spotify auth to authenticate and create the token file.
2. Verify you run commands as the same user/HOME that performed the auth (token files are per-user).
3. If tokens exist but aren't found, check the token storage path/permissions.

Example fix

// before
opencli spotify search "daft punk"  // AUTH_REQUIRED
// after
opencli spotify auth
opencli spotify search "daft punk"

import fs from 'node:fs';
if (!fs.existsSync(TOKEN_PATH)) { console.error('Not authenticated. Run: opencli spotify auth'); process.exit(1); }

try {
  await spotifyCommand(args);
} catch (e) {
  if (e.code === 'AUTH_REQUIRED') {
    await runAuthFlow(); // or instruct: opencli spotify auth
    await spotifyCommand(args); // retry once after auth
  } else throw e;
}

When it happens

Trigger: Running any spotify command (e.g. opencli spotify play/search) before ever running opencli spotify auth, or after the token file was deleted from its storage location.

Common situations: Fresh install or new machine; CI/container without a persisted token file; token file removed by cleanup or a different HOME/user; typo'd profile so loadTokens looks in the wrong path.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• AUTH_CORRUPTED
• CONFIG
• REFRESH_FAILED
• Missing Xiaoyuzhou credentials. Expected ${filePath}
• 12306 tk auth cookie missing

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/7c4112a7c9f2308e. Report an issue: GitHub.