feat: support configurable API base URL

Add KIT_API_BASE env var and `kit config set-base-url` so the CLI can target non-production environments. OAuth authorize/token endpoints derive from the base URL; default remains https://api.kit.com/v4.

Author: imjohnbo

README.md

@@ -35,6 +35,18 @@ kit config set-api-key <key>
 
 When both are present, OAuth takes priority.
 
+### Targeting a different environment
+
+By default the CLI talks to production (`https://api.kit.com/v4`). To point it at a different environment (e.g. a staging or test instance), override the API base URL:
+
+```
+kit config set-base-url https://api.example.com/v4
+# or, per-invocation without changing stored config:
+export KIT_API_BASE=https://api.example.com/v4
+```
+
+OAuth authorize/token endpoints derive from this base, so logging in targets the same environment. OAuth apps and credentials are environment-specific — register an app in that environment's developer settings and use its client ID.
+
 ## Commands
 
 ```

scripts/client.test.js

@@ -355,15 +355,25 @@ describe('safeJsonParse', () => {
 
 describe('HTTP client', () => {
   let _oauthSnap;
+  let _baseSnap;
 
   before(() => {
     process.env.KIT_API_KEY = TEST_API_KEY;
+    // Pin the base URL so URL assertions are independent of stored config
+    // (the base URL is configurable via KIT_API_BASE / `kit config set-base-url`).
+    _baseSnap = process.env.KIT_API_BASE;
+    process.env.KIT_API_BASE = 'https://api.kit.com/v4';
     _oauthSnap = oauthSnapshot();
     clearOAuth(); // force API-key auth path; avoids expired-token refresh
   });
 
   after(() => {
     delete process.env.KIT_API_KEY;
+    if (_baseSnap !== undefined) {
+      process.env.KIT_API_BASE = _baseSnap;
+    } else {
+      delete process.env.KIT_API_BASE;
+    }
     restoreOAuth(_oauthSnap);
     globalThis.fetch = _originalFetch;
   });

scripts/config.test.js

@@ -7,7 +7,7 @@
  */
 import { test, describe, before, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { setApiKey, getApiKey, getOAuthClientId, getOAuthRedirectUri } from '../src/config.js';
+import { setApiKey, getApiKey, getOAuthClientId, getOAuthRedirectUri, setBaseUrl, getBaseUrl } from '../src/config.js';
 
 // ── setApiKey – validation (throws before writing to disk) ─────────────────
 
@@ -102,6 +102,89 @@ describe('setApiKey validation', () => {
   });
 });
 
+// ── setBaseUrl – validation (throws before writing to disk) ────────────────
+
+describe('setBaseUrl validation', () => {
+  test('throws for empty string', () => {
+    assert.throws(
+      () => setBaseUrl(''),
+      { message: 'Base URL must be a non-empty string.' }
+    );
+  });
+
+  test('throws for whitespace-only string', () => {
+    assert.throws(
+      () => setBaseUrl('   '),
+      { message: 'Base URL must be a non-empty string.' }
+    );
+  });
+
+  test('throws for null', () => {
+    assert.throws(
+      () => setBaseUrl(null),
+      { message: 'Base URL must be a non-empty string.' }
+    );
+  });
+
+  test('throws for non-string value (number)', () => {
+    assert.throws(
+      () => setBaseUrl(12345),
+      { message: 'Base URL must be a non-empty string.' }
+    );
+  });
+
+  test('throws for a value that is not a valid URL', () => {
+    assert.throws(
+      () => setBaseUrl('not-a-url'),
+      /Invalid base URL/
+    );
+  });
+
+  test('throws for a non-http(s) protocol', () => {
+    assert.throws(
+      () => setBaseUrl('ftp://api.kit.com/v4'),
+      { message: 'Base URL must use http or https.' }
+    );
+  });
+});
+
+// ── getBaseUrl – environment variable override + normalization ─────────────
+
+describe('getBaseUrl', () => {
+  let _saved;
+
+  before(() => {
+    _saved = process.env.KIT_API_BASE;
+    delete process.env.KIT_API_BASE;
+  });
+
+  after(() => {
+    if (_saved !== undefined) {
+      process.env.KIT_API_BASE = _saved;
+    } else {
+      delete process.env.KIT_API_BASE;
+    }
+  });
+
+  test('returns KIT_API_BASE env var when set', () => {
+    process.env.KIT_API_BASE = 'https://api.example.com/v4';
+    assert.equal(getBaseUrl(), 'https://api.example.com/v4');
+    delete process.env.KIT_API_BASE;
+  });
+
+  test('strips trailing slashes from the env var value', () => {
+    process.env.KIT_API_BASE = 'https://api.example.com/v4/';
+    assert.equal(getBaseUrl(), 'https://api.example.com/v4');
+    delete process.env.KIT_API_BASE;
+  });
+
+  test('returns an http(s) URL when neither env nor config overrides it', () => {
+    const val = getBaseUrl();
+    assert.equal(typeof val, 'string');
+    assert.match(val, /^https?:\/\//);
+  });
+});
+
 // ── getApiKey – environment variable override ──────────────────────────────
 
 describe('getApiKey', () => {

src/auth.js

@@ -1,13 +1,17 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
 import { execFile } from 'node:child_process';
-import { setTokens, getOAuthClientId, getRefreshToken, getOAuthRedirectUri } from './config.js';
+import { setTokens, getOAuthClientId, getRefreshToken, getOAuthRedirectUri, getBaseUrl } from './config.js';
 
 const REDIRECT_PORT = 9876;
-const AUTHORIZE_URL = 'https://api.kit.com/v4/oauth/authorize';
-const TOKEN_URL = 'https://api.kit.com/v4/oauth/token';
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 
+// OAuth endpoints derive from the configured base URL so they target the same
+// environment as API calls. The API host redirects the authorize request to
+// its app host automatically.
+const authorizeUrl = () => `${getBaseUrl()}/oauth/authorize`;
+const tokenUrl = () => `${getBaseUrl()}/oauth/token`;
+
 function base64url(buf) {
   return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
 }
@@ -68,7 +72,7 @@ function waitForCallback() {
 }
 
 async function exchangeCode(clientId, code, verifier) {
-  const res = await fetch(TOKEN_URL, {
+  const res = await fetch(tokenUrl(), {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
     body: JSON.stringify({
@@ -96,7 +100,7 @@ export async function refreshAccessToken() {
     throw new Error('No refresh token available. Run `kit login` to re-authenticate.');
   }
 
-  const res = await fetch(TOKEN_URL, {
+  const res = await fetch(tokenUrl(), {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
     body: JSON.stringify({
@@ -121,7 +125,7 @@ export async function login(clientId) {
   const challenge = generateCodeChallenge(verifier);
   const state = base64url(randomBytes(16));
 
-  const authUrl = new URL(AUTHORIZE_URL);
+  const authUrl = new URL(authorizeUrl());
   authUrl.searchParams.set('client_id', clientId);
   authUrl.searchParams.set('response_type', 'code');
   authUrl.searchParams.set('redirect_uri', getOAuthRedirectUri());

src/client.js

@@ -1,7 +1,6 @@
-import { getApiKey, getAccessToken, isTokenExpired } from './config.js';
+import { getApiKey, getAccessToken, isTokenExpired, getBaseUrl } from './config.js';
 import { refreshAccessToken } from './auth.js';
 
-const BASE_URL = 'https://api.kit.com/v4';
 const MAX_PAGINATE_PAGES = 100;
 
 class KitApiError extends Error {
@@ -76,7 +75,7 @@ async function getAuthHeader() {
 }
 
 async function request(method, path, { body, query } = {}) {
-  const url = new URL(`${BASE_URL}${path}`);
+  const url = new URL(`${getBaseUrl()}${path}`);
 
   if (query) {
     for (const [k, v] of Object.entries(query)) {

src/commands/account.js

@@ -4,6 +4,7 @@ import { printDetail, printSuccess, addFormatOption, withErrorHandler } from '..
 import {
   getAll,
   setApiKey,
+  setBaseUrl,
   setOAuthClientId,
   setOAuthRedirectUri,
   setDefaultFormat,
@@ -51,6 +52,19 @@ export function configCommand() {
       }
     });
 
+  cmd
+    .command('set-base-url <url>')
+    .description('Set the API base URL (default: https://api.kit.com/v4)')
+    .action((url) => {
+      try {
+        setBaseUrl(url);
+        console.log(chalk.green('✓ API base URL saved.'));
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+      }
+    });
+
   cmd
     .command('set-api-key <key>')
     .description('Set your Kit API key')

src/config.js

@@ -5,6 +5,7 @@ const config = new Conf({
   projectName: 'kit-cli',
   schema: {
     apiKey:         { type: 'string', default: '' },
+    baseUrl:        { type: 'string', default: 'https://api.kit.com/v4' },
     defaultFormat:  { type: 'string', default: 'table', enum: ['table', 'json'] },
     perPage:        { type: 'number', default: 50, minimum: 1, maximum: 1000 },
     oauthClientId:  { type: 'string', default: '' },
@@ -22,6 +23,41 @@ try {
   // May fail on Windows or if file doesn't exist yet — non-fatal
 }
 
+// --- API base URL ---
+//
+// Defaults to production. Override for other environments (e.g. QA) via the
+// KIT_API_BASE env var or `kit config set-base-url`. The env var wins so you
+// can target a different host for a single invocation without mutating stored
+// config. All API requests and OAuth endpoints derive from this value.
+
+const DEFAULT_BASE_URL = 'https://api.kit.com/v4';
+
+function normalizeBaseUrl(url) {
+  return url.trim().replace(/\/+$/, ''); // strip trailing slashes so path joins don't double up
+}
+
+export function getBaseUrl() {
+  const fromEnv = process.env.KIT_API_BASE;
+  const value = (fromEnv && fromEnv.trim()) || config.get('baseUrl') || DEFAULT_BASE_URL;
+  return normalizeBaseUrl(value);
+}
+
+export function setBaseUrl(url) {
+  if (!url || typeof url !== 'string' || url.trim().length === 0) {
+    throw new Error('Base URL must be a non-empty string.');
+  }
+  let parsed;
+  try {
+    parsed = new URL(url.trim());
+  } catch {
+    throw new Error(`Invalid base URL: "${url}". Must be a full URL like https://api.kit.com/v4.`);
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error('Base URL must use http or https.');
+  }
+  config.set('baseUrl', normalizeBaseUrl(url));
+}
+
 // --- API key ---
 
 export function getApiKey() {
@@ -123,6 +159,7 @@ export function getAll() {
   }
 
   return {
+    baseUrl:         getBaseUrl(),
     apiKey:          getApiKey() ? '****' + getApiKey().slice(-4) : '(not set)',
     oauthClientId:   getOAuthClientId() || '(not set)',
     oauthRedirectUri: getOAuthRedirectUri(),