fastpass-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cory Wilkerson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# fastpass
+
+Cloudflare Access in 60 seconds. No enterprise jargon.
+
+## What you want → What it does
+
+| You want...                        | Cloudflare calls it...         | fastpass handles it |
+|------------------------------------|--------------------------------|----------------------|
+| A login page on my app             | Self-hosted Access Application | `protect`            |
+| GitHub/Google login                | Identity Provider (IdP)        | `--auth github`      |
+| "Only my team can access this"     | Access Policy (Allow rule)     | `--allow`            |
+| "Only my GitHub org"               | GitHub Organization rule       | `--allow "org:name"` |
+| Email-based login, no passwords    | One-Time PIN (OTP)             | `--auth email`       |
+| The wall that checks your identity | Cloudflare Access              | all of it            |
+
+## Quickstart
+
+```sh
+npx fastpass
+```
+
+That's it. The interactive wizard walks you through everything.
+
+## One-liners
+
+```sh
+# Protect with email login (zero config)
+npx fastpass protect staging.myapp.com --auth email --allow "me@gmail.com"
+
+# Protect with GitHub login, allow anyone at your company
+npx fastpass protect staging.myapp.com --auth github --allow "*@company.com"
+
+# Protect with GitHub login, restrict to a GitHub org
+npx fastpass protect staging.myapp.com --auth github --allow "org:my-github-org"
+
+# Protect with Google login, allow everyone (just require login)
+npx fastpass protect admin.myapp.com --auth google --allow "everyone"
+
+# List protected domains
+npx fastpass list
+
+# Remove protection
+npx fastpass remove staging.myapp.com
+
+# Overview dashboard — team, apps, IdPs, recent activity
+npx fastpass status
+
+# Recent access events (last 25)
+npx fastpass logs
+
+# Filter events to one domain, last 10
+npx fastpass logs staging.myapp.com --limit 10
+
+# Events since a specific date
+npx fastpass logs --since 2025-01-15
+
+# Detailed config for a specific app
+npx fastpass inspect staging.myapp.com
+
+# Interactive app picker
+npx fastpass inspect
+```
+
+## Prerequisites
+
+### 1. Enable Cloudflare Access (one-time)
+
+Before fastpass can do anything, Access needs to be turned on for your account:
+
+1. Go to [https://one.dash.cloudflare.com](https://one.dash.cloudflare.com) (Zero Trust dashboard)
+2. You'll be prompted to select the **Free** plan ($0) — confirm it
+3. Pick a **team name** (e.g. `myteam`) — this becomes `myteam.cloudflareaccess.com`, the login domain for all your protected apps
+
+This only needs to happen once per account.
+
+### 2. API credentials
+
+You need a Cloudflare API token. Pick one:
+
+### Option A: API Token (recommended)
+
+1. Go to https://dash.cloudflare.com/profile/api-tokens
+2. Create a token with these permissions:
+   - **Access: Organizations, Identity Providers, and Groups** — Edit
+   - **Access: Apps and Policies** — Edit
+   - **Zone: Zone** — Read
+3. Set the env var:
+
+```sh
+export CLOUDFLARE_API_TOKEN="your-token"
+```
+
+Optionally set `CLOUDFLARE_ACCOUNT_ID` if you have multiple accounts.
+
+### Option B: Wrangler login
+
+If you already use wrangler:
+
+```sh
+npx wrangler login
+npx fastpass
+```
+
+> **Note:** Wrangler's default OAuth token does not include Access scopes. If you use `wrangler login` for deploying Workers but get permission errors from fastpass, you'll need a dedicated API token (Option A). The wrangler OAuth scopes cover Workers, KV, D1, Pages, etc. — but not Cloudflare Access.
+
+## Auth methods
+
+### Email code (OTP)
+
+The easiest option. No external setup required. Users get a one-time code sent to their email.
+
+### GitHub
+
+fastpass walks you through creating a GitHub OAuth app. You'll need to:
+1. Create an OAuth app at https://github.com/settings/developers
+2. Paste the Client ID and Secret when prompted
+
+### Google
+
+Same as GitHub — fastpass guides you through the Google Cloud Console OAuth setup.
+
+## How it works
+
+Under the hood, fastpass calls the Cloudflare API to:
+
+1. **Validate** your domain exists in your CF account
+2. **Create an Identity Provider** (email OTP, GitHub, or Google OAuth)
+3. **Create an Access Application** on your domain with an allow policy
+4. Your domain now shows a login page before granting access
+
+All of this maps to Cloudflare's [Zero Trust Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) product — fastpass just removes the jargon and manual steps.
+
+## FAQ
+
+**Does this cost money?**
+Cloudflare Access is free for up to 50 users.
+
+**Can I use multiple auth methods?**
+Run `protect` again on the same domain with a different `--auth` flag, or configure additional IdPs in the CF dashboard.
+
+**What if I already have Access set up?**
+fastpass detects existing identity providers and reuses them.
+
+**How do I see what's going on?**
+Run `npx fastpass status` for an overview, `npx fastpass logs` for recent events, or `npx fastpass inspect <domain>` for detailed app config.
+
+**How do I manage users/policies after setup?**
+Use the [Cloudflare Zero Trust dashboard](https://one.dash.cloudflare.com).

package/bin/fastpass.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "fastpass-cli",
+  "version": "0.1.0",
+  "description": "Cloudflare Access in 60 seconds. No enterprise jargon.",
+  "type": "module",
+  "bin": {
+    "fastpass": "./bin/fastpass.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skill/"
+  ],
+  "keywords": [
+    "cloudflare",
+    "access",
+    "auth",
+    "login",
+    "zero-trust",
+    "cli"
+  ],
+  "author": "Cory Wilkerson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/corywilkerson/fastpass.git"
+  },
+  "homepage": "https://github.com/corywilkerson/fastpass#readme",
+  "bugs": {
+    "url": "https://github.com/corywilkerson/fastpass/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^13.0.0",
+    "open": "^10.0.0",
+    "picocolors": "^1.1.0"
+  }
+}

package/skill/fastpass-skill.md

@@ -0,0 +1,92 @@
+---
+name: fastpass
+description: Protect a domain with Cloudflare Access — interactive or one-liner
+user_invocable: true
+---
+
+# fastpass: Cloudflare Access for Humans
+
+You are helping the user set up Cloudflare Access on their domain using the `fastpass` CLI tool.
+
+## What you can do
+
+- **Protect a domain** with a login page (email code, GitHub, or Google)
+- **List** currently protected domains
+- **Remove** protection from a domain
+- **Status** — overview dashboard of team, apps, IdPs, and recent activity
+- **Logs** — view recent access events, optionally filtered by domain
+- **Inspect** — deep dive into a specific app's configuration and policies
+
+## How to use
+
+### Interactive mode
+Run the wizard and let the user answer prompts:
+```bash
+npx fastpass
+```
+
+### One-liner mode
+If the user has already told you the domain, auth method, and who should have access:
+```bash
+npx fastpass protect <domain> --auth <email|github|google> --allow "<rule>"
+```
+
+Allow rules:
+- `"me@email.com"` — specific email(s), comma-separated
+- `"*@company.com"` — anyone with that email domain
+- `"org:my-github-org"` — members of a GitHub organization (use with `--auth github`)
+- `"everyone"` — just require login, allow all
+
+### List protected domains
+```bash
+npx fastpass list
+```
+
+### Remove protection
+```bash
+npx fastpass remove <domain>
+```
+
+### Status dashboard
+```bash
+npx fastpass status
+```
+
+### View recent access logs
+```bash
+npx fastpass logs [domain] --limit 25 --since 2025-01-15
+```
+
+Options:
+- `[domain]` — optional, filter events to a specific domain
+- `--limit <n>` — number of events (default 25)
+- `--since <date>` — only events after this date (ISO 8601)
+
+### Inspect app configuration
+```bash
+npx fastpass inspect [domain]
+```
+
+If no domain is provided, shows an interactive picker. Displays: domain, type, session duration, allowed identity providers (resolved to names), and policy rules translated to plain English.
+
+## Prerequisites
+
+The user needs Cloudflare credentials. Check if they have either:
+1. `CLOUDFLARE_API_TOKEN` env var set, OR
+2. `npx wrangler login` already done
+
+If not, help them create an API token at https://dash.cloudflare.com/profile/api-tokens with:
+- Access: Organizations, Identity Providers, and Groups — Edit
+- Access: Apps and Policies — Edit
+- Zone: Zone — Read
+
+## Conversational flow
+
+When the user asks to protect a domain, gather these three things:
+1. **Domain** — what domain to protect (must be in their CF account)
+2. **Auth method** — email (easiest), github, or google
+3. **Access rule** — who should be allowed in
+
+Then construct and run the appropriate `npx fastpass` command.
+
+If the user is unsure, recommend **email** auth — it requires zero external setup.

package/src/api.js

@@ -0,0 +1,63 @@
+import pc from 'picocolors';
+
+const BASE = 'https://api.cloudflare.com/client/v4';
+
+export function createApi({ token, accountId }) {
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  };
+
+  const accountPath = `/accounts/${accountId}`;
+
+  async function request(method, path, body) {
+    // Paths starting with / but not /accounts or /zones get the account prefix
+    const fullPath = path.startsWith('/zones') || path.startsWith('/accounts')
+      ? path
+      : `${accountPath}${path}`;
+
+    const url = `${BASE}${fullPath}`;
+
+    const opts = { method, headers };
+    if (body) opts.body = JSON.stringify(body);
+
+    const res = await fetch(url, opts);
+    const json = await res.json();
+
+    if (!json.success) {
+      const errors = json.errors?.map((e) => e.message).join(', ') || 'Unknown error';
+      throw new ApiError(errors, json.errors, res.status);
+    }
+
+    return json;
+  }
+
+  return {
+    get: (path) => request('GET', path),
+    post: (path, body) => request('POST', path, body),
+    put: (path, body) => request('PUT', path, body),
+    delete: (path) => request('DELETE', path),
+  };
+}
+
+export class ApiError extends Error {
+  constructor(message, errors, status) {
+    super(message);
+    this.name = 'ApiError';
+    this.errors = errors;
+    this.status = status;
+  }
+}
+
+export function handleApiError(err) {
+  if (err instanceof ApiError) {
+    console.error(pc.red(`\nCloudflare API error: ${err.message}`));
+    if (err.status === 403) {
+      console.error(pc.yellow('Your API token may not have the required permissions.'));
+      console.error('Needed scopes: Access: Organizations + Identity Providers + Apps and Policies (Edit)\n');
+    }
+  } else {
+    console.error(pc.red(`\nError: ${err.message}\n`));
+  }
+  process.exit(1);
+}

package/src/auth.js

@@ -0,0 +1,93 @@
+import { execSync } from 'node:child_process';
+import pc from 'picocolors';
+
+/**
+ * Resolve Cloudflare credentials.
+ *
+ * Priority:
+ *  1. CLOUDFLARE_API_TOKEN env var
+ *  2. `wrangler auth token` fallback (OAuth token)
+ *
+ * Account ID:
+ *  1. CLOUDFLARE_ACCOUNT_ID env var
+ *  2. Fetched from /accounts API
+ */
+export async function getCredentials() {
+  let token = process.env.CLOUDFLARE_API_TOKEN;
+
+  if (!token) {
+    token = tryWranglerToken();
+  }
+
+  if (!token) {
+    console.error(pc.red('\nCould not find Cloudflare credentials.\n'));
+    console.error('Set one of the following:\n');
+    console.error(`  ${pc.bold('CLOUDFLARE_API_TOKEN')}  — API token (recommended)`);
+    console.error(`                         Create one at https://dash.cloudflare.com/profile/api-tokens`);
+    console.error(`                         Needs ${pc.cyan('Access: Organizations, Identity Providers, and Groups — Edit')}`);
+    console.error(`                         and   ${pc.cyan('Access: Apps and Policies — Edit')}\n`);
+    console.error(`  Or install ${pc.bold('wrangler')} and run ${pc.cyan('npx wrangler login')} first.\n`);
+    process.exit(1);
+  }
+
+  let accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+
+  if (!accountId) {
+    accountId = await fetchAccountId(token);
+  }
+
+  return { token, accountId };
+}
+
+function tryWranglerToken() {
+  try {
+    const result = execSync('npx wrangler --version 2>/dev/null && npx wrangler auth token 2>/dev/null', {
+      encoding: 'utf-8',
+      timeout: 15000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const trimmed = result.trim();
+    if (trimmed && !trimmed.includes('Error') && !trimmed.includes('error')) {
+      return trimmed;
+    }
+  } catch {
+    // wrangler not available or not logged in
+  }
+  return null;
+}
+
+async function fetchAccountId(token) {
+  const res = await fetch('https://api.cloudflare.com/client/v4/accounts?per_page=5', {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const json = await res.json();
+
+  if (!json.success || !json.result?.length) {
+    console.error(pc.red('Could not determine your Cloudflare account ID.'));
+    console.error(`Set ${pc.bold('CLOUDFLARE_ACCOUNT_ID')} in your environment.\n`);
+    process.exit(1);
+  }
+
+  if (json.result.length === 1) {
+    return json.result[0].id;
+  }
+
+  // Multiple accounts — pick the first, but warn
+  console.warn(pc.yellow(`Multiple Cloudflare accounts found. Using: ${json.result[0].name}`));
+  console.warn(`Set ${pc.bold('CLOUDFLARE_ACCOUNT_ID')} to choose a specific account.\n`);
+  return json.result[0].id;
+}
+
+/**
+ * Fetch the Access organization team name (needed for IdP callback URLs).
+ */
+export async function getTeamName(api) {
+  const { result } = await api.get('/access/organizations');
+
+  if (result?.auth_domain) {
+    // auth_domain looks like "myteam.cloudflareaccess.com"
+    return result.auth_domain.replace('.cloudflareaccess.com', '');
+  }
+
+  return null;
+}

package/src/cli.js

@@ -0,0 +1,87 @@
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { getCredentials } from './auth.js';
+import { createApi } from './api.js';
+import { protect } from './commands/protect.js';
+import { list } from './commands/list.js';
+import { remove } from './commands/remove.js';
+import { status } from './commands/status.js';
+import { logs } from './commands/logs.js';
+import { inspect } from './commands/inspect.js';
+
+export function run() {
+  const program = new Command();
+
+  program
+    .name('fastpass')
+    .description('Cloudflare Access in 60 seconds. No enterprise jargon.')
+    .version('0.1.0');
+
+  // Default action (no subcommand) — run the protect wizard
+  program
+    .command('protect [domain]', { isDefault: true })
+    .description('Protect a domain with Cloudflare Access')
+    .option('--auth <method>', 'Auth method: email, github, or google')
+    .option('--allow <rule>', 'Who can access: email, *@domain.com, or "everyone"')
+    .action(async (domain, opts) => {
+      printBanner();
+      const creds = await getCredentials();
+      const api = createApi(creds);
+      await protect(api, { domain, ...opts });
+    });
+
+  program
+    .command('list')
+    .description('List protected domains')
+    .action(async () => {
+      const creds = await getCredentials();
+      const api = createApi(creds);
+      await list(api);
+    });
+
+  program
+    .command('remove [domain]')
+    .description('Remove protection from a domain')
+    .action(async (domain) => {
+      const creds = await getCredentials();
+      const api = createApi(creds);
+      await remove(api, { domain });
+    });
+
+  program
+    .command('status')
+    .description('Show Access overview: team, apps, IdPs, and recent activity')
+    .action(async () => {
+      const creds = await getCredentials();
+      const api = createApi(creds);
+      await status(api);
+    });
+
+  program
+    .command('logs [domain]')
+    .description('Show recent access events')
+    .option('--limit <n>', 'Number of events to show', '25')
+    .option('--since <date>', 'Only show events after this date (ISO 8601)')
+    .action(async (domain, opts) => {
+      const creds = await getCredentials();
+      const api = createApi(creds);
+      await logs(api, { domain, limit: parseInt(opts.limit, 10), since: opts.since });
+    });
+
+  program
+    .command('inspect [domain]')
+    .description('Show detailed configuration for an Access application')
+    .action(async (domain) => {
+      const creds = await getCredentials();
+      const api = createApi(creds);
+      await inspect(api, { domain });
+    });
+
+  program.parse();
+}
+
+function printBanner() {
+  console.log('');
+  console.log(`  ${pc.bold('fastpass')}: protect your app in 60 seconds`);
+  console.log('');
+}

package/src/commands/inspect.js

@@ -0,0 +1,106 @@
+import pc from 'picocolors';
+import { select } from '@inquirer/prompts';
+import { handleApiError } from '../api.js';
+
+/**
+ * Inspect a specific Access application's detailed configuration.
+ */
+export async function inspect(api, opts = {}) {
+  try {
+    const [{ result: apps }, { result: idps }] = await Promise.all([
+      api.get('/access/apps'),
+      api.get('/access/identity_providers'),
+    ]);
+
+    const selfHosted = apps?.filter((a) => a.type === 'self_hosted') || [];
+
+    if (!selfHosted.length) {
+      console.log(pc.dim('\n  No Access applications found.\n'));
+      return;
+    }
+
+    // Build IdP lookup map
+    const idpMap = new Map();
+    for (const idp of idps || []) {
+      idpMap.set(idp.id, idp);
+    }
+
+    let target;
+
+    if (opts.domain) {
+      target = selfHosted.find((app) => app.domain === opts.domain);
+      if (!target) {
+        console.error(pc.red(`\n  No Access application found for domain: ${opts.domain}\n`));
+        process.exit(1);
+      }
+    } else {
+      target = await select({
+        message: 'Which application do you want to inspect?',
+        choices: selfHosted.map((app) => ({
+          value: app,
+          name: `${app.domain || app.name} (${app.id})`,
+        })),
+      });
+    }
+
+    // --- App details ---
+    console.log(`\n  ${pc.bold('Application')}`);
+    console.log(pc.dim(`  ${'─'.repeat(50)}`));
+    console.log(`  Domain:           ${target.domain || 'n/a'}`);
+    console.log(`  Type:             ${target.type || 'n/a'}`);
+    console.log(`  Session duration: ${target.session_duration || 'default'}`);
+    console.log(`  App ID:           ${pc.dim(target.id)}`);
+
+    // --- Allowed IdPs ---
+    console.log(`\n  ${pc.bold('Identity Providers')}`);
+    console.log(pc.dim(`  ${'─'.repeat(50)}`));
+    if (target.allowed_idps?.length) {
+      for (const idpId of target.allowed_idps) {
+        const idp = idpMap.get(idpId);
+        if (idp) {
+          console.log(`  ${idp.name} (${idp.type})`);
+        } else {
+          console.log(`  ${pc.dim(idpId)} (unknown)`);
+        }
+      }
+    } else {
+      console.log(pc.dim('  Any provider'));
+    }
+
+    // --- Policies ---
+    console.log(`\n  ${pc.bold('Policies')}`);
+    console.log(pc.dim(`  ${'─'.repeat(50)}`));
+    if (target.policies?.length) {
+      for (const policy of target.policies) {
+        console.log(`  ${pc.cyan(policy.name || 'Unnamed')} — ${policy.decision || 'n/a'}`);
+        if (policy.include?.length) {
+          for (const rule of policy.include) {
+            console.log(`    ${describeRule(rule)}`);
+          }
+        }
+      }
+    } else {
+      console.log(pc.dim('  No policies configured'));
+    }
+
+    console.log('');
+  } catch (err) {
+    handleApiError(err);
+  }
+}
+
+function describeRule(rule) {
+  if (rule.email?.email) {
+    return rule.email.email;
+  }
+  if (rule.email_domain?.domain) {
+    return `Anyone with an @${rule.email_domain.domain} email`;
+  }
+  if (rule['github-organization']?.name) {
+    return `Members of GitHub org "${rule['github-organization'].name}"`;
+  }
+  if ('everyone' in rule) {
+    return 'Everyone (any logged-in user)';
+  }
+  return JSON.stringify(rule);
+}

package/src/commands/list.js

@@ -0,0 +1,48 @@
+import pc from 'picocolors';
+import { handleApiError } from '../api.js';
+
+/**
+ * List all Access applications in the account.
+ */
+export async function list(api) {
+  try {
+    const { result } = await api.get('/access/apps');
+
+    if (!result?.length) {
+      console.log(pc.dim('\n  No Access applications found.\n'));
+      console.log(`  Run ${pc.cyan('fastpass protect <domain>')} to get started.\n`);
+      return;
+    }
+
+    // Filter to self-hosted apps (the ones fastpass creates)
+    const apps = result.filter((app) => app.type === 'self_hosted');
+
+    if (!apps.length) {
+      console.log(pc.dim('\n  No self-hosted Access applications found.\n'));
+      return;
+    }
+
+    console.log(`\n  ${pc.bold('Protected domains')}\n`);
+
+    const maxDomain = Math.max(...apps.map((a) => (a.domain || '').length), 6);
+
+    console.log(
+      `  ${pc.dim('Domain'.padEnd(maxDomain + 2))}${pc.dim('Auth'.padEnd(18))}${pc.dim('Session')}`,
+    );
+    console.log(pc.dim(`  ${'─'.repeat(maxDomain + 2)}${'─'.repeat(18)}${'─'.repeat(10)}`));
+
+    for (const app of apps) {
+      const domain = (app.domain || 'n/a').padEnd(maxDomain + 2);
+      const idpNames = app.allowed_idps?.length
+        ? `${app.allowed_idps.length} provider(s)`
+        : 'any';
+      const session = app.session_duration || 'default';
+
+      console.log(`  ${domain}${idpNames.padEnd(18)}${session}`);
+    }
+
+    console.log(`\n  ${pc.dim(`${apps.length} application(s)`)}\n`);
+  } catch (err) {
+    handleApiError(err);
+  }
+}

package/src/commands/logs.js

@@ -0,0 +1,77 @@
+import pc from 'picocolors';
+import { handleApiError } from '../api.js';
+
+/**
+ * Show recent access log events, optionally filtered by domain.
+ */
+export async function logs(api, opts = {}) {
+  try {
+    const limit = opts.limit || 25;
+
+    // Validate --since if provided
+    let sinceParam = '';
+    if (opts.since) {
+      const parsed = new Date(opts.since);
+      if (isNaN(parsed.getTime())) {
+        console.error(pc.red(`\n  Invalid date: ${opts.since}`));
+        console.error('  Use ISO 8601 format, e.g. 2025-01-15 or 2025-01-15T00:00:00Z\n');
+        process.exit(1);
+      }
+      sinceParam = `&since=${parsed.toISOString()}`;
+    }
+
+    const { result } = await api.get(
+      `/access/logs/access_requests?limit=${limit}&direction=desc${sinceParam}`,
+    );
+
+    if (!result?.length) {
+      console.log(pc.dim('\n  No access events found.\n'));
+      return;
+    }
+
+    // Client-side domain filter
+    const domain = opts.domain;
+    const events = domain
+      ? result.filter((e) => e.app_domain === domain)
+      : result;
+
+    if (!events.length) {
+      console.log(pc.dim(`\n  No events found for domain: ${domain}\n`));
+      return;
+    }
+
+    console.log(`\n  ${pc.bold('Recent Access Events')}${domain ? ` — ${domain}` : ''}\n`);
+
+    const colTime = Math.max(...events.map((e) => formatTime(e.created_at).length), 4);
+    const colEmail = Math.max(...events.map((e) => (e.user_email || '').length), 5);
+    const colDomain = Math.max(...events.map((e) => (e.app_domain || '').length), 6);
+
+    console.log(
+      `  ${pc.dim('Time'.padEnd(colTime + 2))}${pc.dim('Email'.padEnd(colEmail + 2))}${pc.dim('Domain'.padEnd(colDomain + 2))}${pc.dim('OK'.padEnd(5))}${pc.dim('IP')}`,
+    );
+    console.log(
+      pc.dim(`  ${'─'.repeat(colTime + 2)}${'─'.repeat(colEmail + 2)}${'─'.repeat(colDomain + 2)}${'─'.repeat(5)}${'─'.repeat(15)}`),
+    );
+
+    for (const e of events) {
+      const time = formatTime(e.created_at).padEnd(colTime + 2);
+      const email = (e.user_email || 'n/a').padEnd(colEmail + 2);
+      const dom = (e.app_domain || 'n/a').padEnd(colDomain + 2);
+      const ok = (e.allowed ? '✓' : '✗').padEnd(5);
+      const ip = e.ip_address || 'n/a';
+
+      const line = `  ${time}${email}${dom}${ok}${ip}`;
+      console.log(e.allowed ? line : pc.red(line));
+    }
+
+    console.log(`\n  ${pc.dim(`${events.length} event(s)`)}\n`);
+  } catch (err) {
+    handleApiError(err);
+  }
+}
+
+function formatTime(iso) {
+  if (!iso) return 'n/a';
+  const d = new Date(iso);
+  return d.toLocaleString();
+}

package/src/commands/protect.js

@@ -0,0 +1,188 @@
+import pc from 'picocolors';
+import { input, select } from '@inquirer/prompts';
+import { getTeamName } from '../auth.js';
+import { ensureEmailOtp } from '../idp/email-otp.js';
+import { ensureGitHub } from '../idp/github.js';
+import { ensureGoogle } from '../idp/google.js';
+import { handleApiError } from '../api.js';
+
+const AUTH_CHOICES = {
+  email: { label: 'Email code (easiest, no setup)', setup: ensureEmailOtp },
+  github: { label: 'GitHub', setup: ensureGitHub },
+  google: { label: 'Google', setup: ensureGoogle },
+};
+
+const ACCESS_CHOICES = {
+  me: 'Just me (enter your email)',
+  domain: 'Anyone with a specific email domain (@company.com)',
+  github_org: 'Members of a GitHub organization',
+  emails: 'Specific email addresses',
+  everyone: 'Everyone (just require login)',
+};
+
+/**
+ * Main protect command — interactive wizard or one-liner.
+ */
+export async function protect(api, opts = {}) {
+  try {
+    const domain = opts.domain || await input({
+      message: 'What domain do you want to protect?',
+      validate: (v) => v.trim().includes('.') || 'Enter a valid domain (e.g. app.example.com)',
+    });
+
+    // Validate domain exists in CF
+    await validateDomain(api, domain.trim());
+
+    const authMethod = opts.auth || await select({
+      message: 'How should people log in?',
+      choices: Object.entries(AUTH_CHOICES).map(([value, { label }]) => ({ value, name: label })),
+    });
+
+    if (!AUTH_CHOICES[authMethod]) {
+      console.error(pc.red(`Unknown auth method: ${authMethod}. Use: email, github, or google`));
+      process.exit(1);
+    }
+
+    // Resolve who gets access
+    const { include, includeType } = await resolveAccess(opts.allow);
+
+    // Get team name for OAuth callback URLs
+    const teamName = await getTeamName(api);
+    if (!teamName && authMethod !== 'email') {
+      console.error(pc.red('Could not determine your Access team name.'));
+      console.error('Make sure Access is enabled in your Cloudflare dashboard.\n');
+      process.exit(1);
+    }
+
+    // Set up the identity provider
+    console.log('');
+    const idp = await AUTH_CHOICES[authMethod].setup(api, teamName);
+
+    // Build the policy include rules
+    const policyInclude = buildIncludeRules(include, includeType);
+
+    // Create the access application with an inline policy
+    console.log(`  Protecting ${pc.bold(domain.trim())}...`);
+
+    const appBody = {
+      name: domain.trim(),
+      domain: domain.trim(),
+      type: 'self_hosted',
+      session_duration: '24h',
+      allowed_idps: [idp.id],
+      auto_redirect_to_identity: true,
+      policies: [
+        {
+          name: `Allow — ${domain.trim()}`,
+          decision: 'allow',
+          include: policyInclude,
+          precedence: 1,
+        },
+      ],
+    };
+
+    const { result: app } = await api.post('/access/apps', appBody);
+
+    console.log(pc.green('  Done!\n'));
+    console.log(`  ${pc.bold('Your app is protected!')} Try visiting:`);
+    console.log(`  ${pc.cyan(`https://${domain.trim()}`)}\n`);
+    console.log(`  Manage it: ${pc.dim('https://one.dash.cloudflare.com')}`);
+    console.log(`  App ID:    ${pc.dim(app.id)}\n`);
+
+    return app;
+  } catch (err) {
+    handleApiError(err);
+  }
+}
+
+async function validateDomain(api, domain) {
+  // Extract the root domain for zone lookup
+  const parts = domain.split('.');
+  const rootDomain = parts.slice(-2).join('.');
+
+  try {
+    const { result } = await api.get(`/zones?name=${rootDomain}`);
+    if (!result?.length) {
+      console.error(pc.red(`\nDomain "${rootDomain}" not found in your Cloudflare account.`));
+      console.error('Make sure the domain is added to your Cloudflare dashboard.\n');
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(pc.red(`\nCould not verify domain: ${err.message}\n`));
+    process.exit(1);
+  }
+}
+
+async function resolveAccess(allowFlag) {
+  // If --allow flag was passed, parse it
+  if (allowFlag) {
+    if (allowFlag.startsWith('*@')) {
+      return { include: [allowFlag.slice(2)], includeType: 'domain' };
+    }
+    if (allowFlag.startsWith('org:')) {
+      return { include: [allowFlag.slice(4)], includeType: 'github_org' };
+    }
+    if (allowFlag === 'everyone') {
+      return { include: [], includeType: 'everyone' };
+    }
+    // Treat as comma-separated email list
+    return { include: allowFlag.split(',').map((e) => e.trim()), includeType: 'emails' };
+  }
+
+  // Interactive
+  const accessType = await select({
+    message: 'Who should have access?',
+    choices: Object.entries(ACCESS_CHOICES).map(([value, name]) => ({ value, name })),
+  });
+
+  switch (accessType) {
+    case 'me': {
+      const email = await input({
+        message: 'Your email address:',
+        validate: (v) => v.includes('@') || 'Enter a valid email',
+      });
+      return { include: [email.trim()], includeType: 'emails' };
+    }
+    case 'domain': {
+      const domain = await input({
+        message: 'Email domain (e.g. company.com):',
+        validate: (v) => v.includes('.') || 'Enter a valid domain',
+      });
+      return { include: [domain.trim()], includeType: 'domain' };
+    }
+    case 'github_org': {
+      const org = await input({
+        message: 'GitHub organization name:',
+        validate: (v) => v.trim().length > 0 || 'Enter a GitHub org name',
+      });
+      return { include: [org.trim()], includeType: 'github_org' };
+    }
+    case 'emails': {
+      const emails = await input({
+        message: 'Email addresses (comma-separated):',
+        validate: (v) => v.includes('@') || 'Enter at least one email',
+      });
+      return { include: emails.split(',').map((e) => e.trim()), includeType: 'emails' };
+    }
+    case 'everyone':
+      return { include: [], includeType: 'everyone' };
+    default:
+      return { include: [], includeType: 'everyone' };
+  }
+}
+
+function buildIncludeRules(include, includeType) {
+  switch (includeType) {
+    case 'emails':
+      // CF API expects one rule per email: [{ email: { email: "a@b.com" } }, ...]
+      return include.map((email) => ({ email: { email } }));
+    case 'domain':
+      return [{ email_domain: { domain: include[0] } }];
+    case 'github_org':
+      return [{ 'github-organization': { name: include[0] } }];
+    case 'everyone':
+      return [{ everyone: {} }];
+    default:
+      return [{ everyone: {} }];
+  }
+}

package/src/commands/remove.js

@@ -0,0 +1,53 @@
+import pc from 'picocolors';
+import { select, confirm } from '@inquirer/prompts';
+import { handleApiError } from '../api.js';
+
+/**
+ * Remove Access protection from a domain.
+ */
+export async function remove(api, opts = {}) {
+  try {
+    const { result } = await api.get('/access/apps');
+    const apps = result?.filter((app) => app.type === 'self_hosted') || [];
+
+    if (!apps.length) {
+      console.log(pc.dim('\n  No Access applications to remove.\n'));
+      return;
+    }
+
+    let target;
+
+    if (opts.domain) {
+      target = apps.find((app) => app.domain === opts.domain);
+      if (!target) {
+        console.error(pc.red(`\n  No Access application found for domain: ${opts.domain}\n`));
+        process.exit(1);
+      }
+    } else {
+      // Interactive selection
+      target = await select({
+        message: 'Which application do you want to remove?',
+        choices: apps.map((app) => ({
+          value: app,
+          name: `${app.domain || app.name} (${app.id})`,
+        })),
+      });
+    }
+
+    const ok = await confirm({
+      message: `Remove Access protection from ${pc.bold(target.domain || target.name)}?`,
+      default: false,
+    });
+
+    if (!ok) {
+      console.log(pc.dim('  Cancelled.\n'));
+      return;
+    }
+
+    console.log(`  Removing ${pc.bold(target.domain || target.name)}...`);
+    await api.delete(`/access/apps/${target.id}`);
+    console.log(pc.green('  Removed.\n'));
+  } catch (err) {
+    handleApiError(err);
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,71 @@
+import pc from 'picocolors';
+import { handleApiError } from '../api.js';
+
+/**
+ * Status dashboard — quick snapshot of Access configuration and recent activity.
+ */
+export async function status(api) {
+  try {
+    const [{ result: org }, { result: apps }, { result: idps }] = await Promise.all([
+      api.get('/access/organizations'),
+      api.get('/access/apps'),
+      api.get('/access/identity_providers'),
+    ]);
+
+    // --- Team info ---
+    const teamName = org?.auth_domain?.replace('.cloudflareaccess.com', '') || 'unknown';
+    console.log(`\n  ${pc.bold('Team')}`);
+    console.log(pc.dim(`  ${'─'.repeat(40)}`));
+    console.log(`  Auth domain: ${org?.auth_domain || 'n/a'}`);
+    console.log(`  Team name:   ${teamName}`);
+
+    // --- Protected apps ---
+    const selfHosted = apps?.filter((a) => a.type === 'self_hosted') || [];
+    console.log(`\n  ${pc.bold('Protected Apps')} (${selfHosted.length})`);
+    console.log(pc.dim(`  ${'─'.repeat(40)}`));
+    if (selfHosted.length) {
+      for (const app of selfHosted) {
+        console.log(`  ${app.domain || app.name}`);
+      }
+    } else {
+      console.log(pc.dim('  None'));
+    }
+
+    // --- Identity providers ---
+    console.log(`\n  ${pc.bold('Identity Providers')} (${idps?.length || 0})`);
+    console.log(pc.dim(`  ${'─'.repeat(40)}`));
+    if (idps?.length) {
+      const maxName = Math.max(...idps.map((p) => (p.name || '').length), 4);
+      console.log(`  ${pc.dim('Name'.padEnd(maxName + 2))}${pc.dim('Type')}`);
+      for (const idp of idps) {
+        console.log(`  ${(idp.name || 'n/a').padEnd(maxName + 2)}${idp.type || 'n/a'}`);
+      }
+    } else {
+      console.log(pc.dim('  None'));
+    }
+
+    // --- Recent activity (graceful fallback) ---
+    console.log(`\n  ${pc.bold('Recent Activity')}`);
+    console.log(pc.dim(`  ${'─'.repeat(40)}`));
+    try {
+      const { result: logs } = await api.get('/access/logs/access_requests?limit=50&direction=desc');
+      if (logs?.length) {
+        let allowed = 0;
+        let denied = 0;
+        for (const entry of logs) {
+          if (entry.allowed) allowed++;
+          else denied++;
+        }
+        console.log(`  Allowed: ${pc.green(String(allowed))}  Denied: ${pc.red(String(denied))}  (last ${logs.length} events)`);
+      } else {
+        console.log(pc.dim('  No recent events'));
+      }
+    } catch {
+      console.log(pc.dim('  Unable to fetch logs (token may lack Access: Audit Logs permission)'));
+    }
+
+    console.log('');
+  } catch (err) {
+    handleApiError(err);
+  }
+}

package/src/idp/email-otp.js

@@ -0,0 +1,25 @@
+import pc from 'picocolors';
+
+/**
+ * Ensure the One-Time PIN (email code) identity provider exists.
+ * Returns the IdP object.
+ */
+export async function ensureEmailOtp(api) {
+  const { result } = await api.get('/access/identity_providers');
+  const existing = result?.find((idp) => idp.type === 'onetimepin');
+
+  if (existing) {
+    console.log(pc.green('  Email Login already configured.'));
+    return existing;
+  }
+
+  console.log('  Setting up Email Login...');
+  const { result: created } = await api.post('/access/identity_providers', {
+    type: 'onetimepin',
+    name: 'Email Login',
+    config: {},
+  });
+
+  console.log(pc.green('  Email Login enabled.'));
+  return created;
+}

package/src/idp/github.js

@@ -0,0 +1,64 @@
+import pc from 'picocolors';
+import { input, confirm } from '@inquirer/prompts';
+import open from 'open';
+
+/**
+ * Ensure a GitHub OAuth identity provider exists.
+ * Guides the user through creating a GitHub OAuth app if needed.
+ */
+export async function ensureGitHub(api, teamName) {
+  const { result } = await api.get('/access/identity_providers');
+  const existing = result?.find((idp) => idp.type === 'github');
+
+  if (existing) {
+    console.log(pc.green('  GitHub login already configured.'));
+    return existing;
+  }
+
+  const callbackUrl = `https://${teamName}.cloudflareaccess.com/cdn-cgi/access/callback`;
+  const homepageUrl = `https://${teamName}.cloudflareaccess.com`;
+
+  console.log('');
+  console.log(pc.bold('  GitHub OAuth Setup'));
+  console.log(pc.dim('  You need to create a GitHub OAuth app. It takes about 30 seconds.\n'));
+
+  console.log(`  1. Go to ${pc.cyan('https://github.com/settings/developers')}`);
+  console.log('  2. Click "New OAuth App"');
+  console.log(`  3. Application name: ${pc.bold('Cloudflare Access')}`);
+  console.log(`  4. Homepage URL:     ${pc.bold(homepageUrl)}`);
+  console.log(`  5. Callback URL:     ${pc.bold(callbackUrl)}`);
+  console.log('  6. Click "Register application"');
+  console.log('  7. Generate a client secret\n');
+
+  const shouldOpen = await confirm({
+    message: 'Open GitHub settings in your browser?',
+    default: true,
+  });
+
+  if (shouldOpen) {
+    await open('https://github.com/settings/developers');
+  }
+
+  const clientId = await input({
+    message: 'GitHub Client ID:',
+    validate: (v) => v.trim().length > 0 || 'Required',
+  });
+
+  const clientSecret = await input({
+    message: 'GitHub Client Secret:',
+    validate: (v) => v.trim().length > 0 || 'Required',
+  });
+
+  console.log('  Creating GitHub identity provider...');
+  const { result: created } = await api.post('/access/identity_providers', {
+    type: 'github',
+    name: 'GitHub',
+    config: {
+      client_id: clientId.trim(),
+      client_secret: clientSecret.trim(),
+    },
+  });
+
+  console.log(pc.green('  GitHub login enabled.'));
+  return created;
+}

package/src/idp/google.js

@@ -0,0 +1,62 @@
+import pc from 'picocolors';
+import { input, confirm } from '@inquirer/prompts';
+import open from 'open';
+
+/**
+ * Ensure a Google OAuth identity provider exists.
+ * Guides the user through creating a Google OAuth client if needed.
+ */
+export async function ensureGoogle(api, teamName) {
+  const { result } = await api.get('/access/identity_providers');
+  const existing = result?.find((idp) => idp.type === 'google');
+
+  if (existing) {
+    console.log(pc.green('  Google login already configured.'));
+    return existing;
+  }
+
+  const callbackUrl = `https://${teamName}.cloudflareaccess.com/cdn-cgi/access/callback`;
+
+  console.log('');
+  console.log(pc.bold('  Google OAuth Setup'));
+  console.log(pc.dim('  You need to create a Google OAuth client. It takes about a minute.\n'));
+
+  console.log(`  1. Go to ${pc.cyan('https://console.cloud.google.com/apis/credentials')}`);
+  console.log('  2. Click "Create Credentials" → "OAuth client ID"');
+  console.log('  3. Application type: "Web application"');
+  console.log(`  4. Name: ${pc.bold('Cloudflare Access')}`);
+  console.log(`  5. Authorized redirect URI: ${pc.bold(callbackUrl)}`);
+  console.log('  6. Click "Create"\n');
+
+  const shouldOpen = await confirm({
+    message: 'Open Google Cloud Console in your browser?',
+    default: true,
+  });
+
+  if (shouldOpen) {
+    await open('https://console.cloud.google.com/apis/credentials');
+  }
+
+  const clientId = await input({
+    message: 'Google Client ID:',
+    validate: (v) => v.trim().length > 0 || 'Required',
+  });
+
+  const clientSecret = await input({
+    message: 'Google Client Secret:',
+    validate: (v) => v.trim().length > 0 || 'Required',
+  });
+
+  console.log('  Creating Google identity provider...');
+  const { result: created } = await api.post('/access/identity_providers', {
+    type: 'google',
+    name: 'Google',
+    config: {
+      client_id: clientId.trim(),
+      client_secret: clientSecret.trim(),
+    },
+  });
+
+  console.log(pc.green('  Google login enabled.'));
+  return created;
+}