@githat/cli

The official GitHat command-line interface. Manage your apps, API keys, and agents from your terminal.

Installation

npm install -g @githat/cli
# or use without installing:
npx @githat/cli <command>

Quick start

npx @githat/cli doctor

This pings api.githat.io, reports your current context (app, org, latency), and tells you if anything needs attention.

Authentication

# Opens a browser to complete auth (requires /dashboard/cli-auth on githat.io)
githat login

# Testing without the browser flow:
githat login --token pk_live_xxxx

# Sign out
githat logout

Note: The browser-based githat login flow requires the /dashboard/cli-auth page on githat.io to be deployed. Until that page is live, use --token for testing.

Command reference

| Command | Description | |---|---| | githat login | Open browser to authenticate; stores token in ~/.githatrc | | githat login --token <tok> | Store token directly (no browser) | | githat logout | Clear ~/.githatrc | | githat whoami | Print user email, org, and current app | | githat apps list | List apps in the current org | | githat apps switch <slug> | Set the active app (persisted in ~/.githatrc) | | githat keys list | List publishable + secret keys for the current app | | githat keys create [--type publishable\|secret] [--name <label>] | Create a new API key | | githat agents list | List registered agents for the current app | | githat doctor | Auth health-check + DNS scan for stale-IP bug across all known hostnames | | githat doctor --dns-only | DNS scan only (no auth ping) | | githat doctor --auth-only | Auth ping only (no DNS scan) | | githat platform init | Add GitHat platform files (.github/) to an existing repo | | githat domains add <hostname> | Provision domain end-to-end: ACM cert + CloudFront distribution + Route 53 aliases | | githat domains list | List GitHat-managed CloudFront distributions with Route 53 aliases | | githat domains list-all | List ALL GitHat-related records across Route 53 + Cloudflare + built-in config | | githat domains rm <hostname> | Remove a domain: disable + delete distribution + delete Route 53 aliases | | githat domains status <hostname> | Probe domain health: cert, distribution, DNS, HTTP 200, security headers | | githat domains heal <hostname> | Auto-fix stale A/AAAA records → CNAME (Cloudflare or Route 53) |

githat doctor

Runs two checks in one command:

1. Auth health-check (original) — pings api.githat.io/auth/me, reports current context (app, org, latency).
2. DNS health-check — scans every hostname in KNOWN_GITHAT_HOSTNAMES (and any extras in ~/.githatrc) for the stale A-record bug: Cloudflare or other DNS provider has hard-coded A/AAAA records pointing at dead IPs instead of a CNAME to the canonical AWS endpoint.

# Full check (auth + DNS)
githat doctor

# DNS scan only — useful in CI
githat doctor --dns-only

# Machine-readable
githat --json doctor --dns-only

Output table columns: hostname | dns type | target | expected | http | status

Status values:

• ✓ healthy — DNS and HTTP are correct
• 🔴 stale-ip — A/AAAA records point at IPs instead of a CNAME; run githat domains heal <hostname>
• 🟡 wrong-target — CNAME exists but points to the wrong host, or HTTP is non-2xx
• 🔴 no-records — no DNS records at all

Extras from ~/.githatrc:

{
  "doctorHostnames": [
    { "hostname": "myapp.example.com", "expected": "d1234.cloudfront.net", "cfProxied": true }
  ]
}

githat domains heal

Diagnoses one hostname and offers to auto-fix the stale-IP bug in-place.

# Diagnose + prompt before mutating
githat domains heal api.githat.io

# Skip confirmation prompt
githat domains heal api.githat.io --yes

Cloudflare zones (requires CF_API_TOKEN env var with Zone:DNS:Edit scope):

1. Lists existing A/AAAA records for the hostname
2. Deletes the bad records via the Cloudflare API
3. Creates a CNAME → expected target (proxied: true for CloudFront, proxied: false for API Gateway)

If CF_API_TOKEN is missing, the command prints instructions for creating one.

Route 53 zones (uses the AWS SDK default credential chain — env vars or ~/.aws/credentials):

1. Finds stale hard-coded A/AAAA records (not aliases) in the zone
2. Deletes them and creates a Route 53 Alias (for CloudFront) or CNAME (for API Gateway)

githat domains

Automates the AWS provisioning workflow used for GitHat reserved domains.

Pre-flight: Your Route 53 hosted zone must already exist. The command errors early with a clear message if no zone is found.

Existing AWS resources referenced (not created):

• CloudFront Function githat-reserved-domain-placeholder — attached on viewer-request for placeholder pages
• Response-headers policy 6c83d2d0-e9a2-4482-ac5f-f6dccae8a1bc — injects HSTS, X-Frame-Options, X-Content-Type-Options, CSP, and Referrer-Policy

githat domains add <hostname>

# Full provisioning — detects zone automatically, uses example.com as origin
githat domains add reserv.click

# Provide the zone explicitly
githat domains add reserv.click --zone Z0123456789ABCDEF

# Use a real origin when your app is deployed
githat domains add shop.colmado.click --origin my-app.us-east-1.amazonaws.com

# Skip www subdomain (apex only)
githat domains add reserv.click --apex-only

# Print resource IDs and exit without waiting (~15 min polling)
githat domains add reserv.click --no-wait

Steps run in order:

1. Auto-detect Route 53 hosted zone (or use --zone)
2. Request ACM certificate in us-east-1 (apex + www. SAN)
3. Add DNS validation CNAME records to Route 53
4. Wait for cert to reach ISSUED
5. Create CloudFront distribution with the CF placeholder function + security-headers policy
6. Wait for distribution to reach Deployed
7. Add Route 53 A + AAAA alias records (apex + www)

githat domains list

githat domains list
githat --json domains list

Returns one row per CloudFront distribution that has aliases and a Route 53 alias record pointing at it. Columns: hostname, distId, status, certArn, origin.

githat domains rm <hostname>

githat domains rm reserv.click

# Start the disable step and exit immediately (safe to re-run later without --no-wait)
githat domains rm reserv.click --no-wait

Steps run in order (each is idempotent — safe to interrupt and resume):

1. Find the CloudFront distribution by alias
2. Disable the distribution (required before delete)
3. Wait for Deployed state
4. Delete Route 53 A + AAAA alias records
5. Delete the distribution

Note: The ACM certificate is NOT deleted — it may be shared with other domains.

Timing: CloudFront disable → Deployed typically takes 10–15 minutes.

githat domains status <hostname>

githat domains status reserv.click

Fast probe without touching the AWS console. Reports:

| check | description | |---|---| | ACM cert | Certificate status (PENDING_VALIDATION / ISSUED / FAILED) | | CF distribution | Distribution ID or "not found" | | DNS resolves | Whether the hostname resolves via local DNS | | HTTP status | HTTP response code (or "unreachable") | | security headers | Whether HSTS / X-Content-Type-Options / X-Frame-Options are present |

githat domains heal <hostname>

See the full description in the githat domains heal section above.

githat domains heal api.githat.io
githat domains heal api.githat.io --yes

githat domains list-all

githat domains list-all
githat --json domains list-all

Enumerates ALL records related to GitHat infrastructure by walking:

• All Route 53 hosted zones (A alias + CNAME records targeting cloudfront.net or amazonaws.com)
• All Cloudflare zones accessible via CF_API_TOKEN (CNAME records)
• The built-in KNOWN_GITHAT_HOSTNAMES list from config

Useful to discover drift when list (CloudFront-only) misses records.

githat platform init

Mirrors the same .github/ directory that create-githat-app scaffolds automatically into any existing repo. Useful for repos that pre-date the scaffold or were cloned without running the tool.

# In your repo root:
githat platform init

# Specify your GitHub handle for CODEOWNERS (defaults to directory name):
githat platform init --github-username your-handle

# Overwrite files that already exist:
githat platform init --force

Files written:

| File | Purpose | |---|---| | .github/dependabot.yml | Weekly Dependabot updates for npm + GitHub Actions | | .github/workflows/ci.yml | Default CI: install → test → build, with ci-failure issue on failure | | .github/workflows/githat-policy.yml | Auto-close PRs that propose alt-auth (Cognito, Auth0, Clerk, Firebase Auth) | | .github/SECURITY.md | Vulnerability disclosure policy pointing at [email protected] | | .github/CODEOWNERS | Auto-request review from your GitHub handle on every PR |

Global flags

| Flag | Description | |---|---| | --json | Output raw JSON on every command (for scripting / CI) | | -v, --version | Print CLI version | | -h, --help | Show help |

JSON output example

githat --json whoami
# {
#   "email": "[email protected]",
#   "userId": "usr_xxxx",
#   "org": "my-org",
#   "app": "my-app"
# }

Configuration file

Credentials and context are stored in ~/.githatrc (permissions 600):

{
  "apiUrl": "https://api.githat.io",
  "accessToken": "...",
  "currentAppSlug": "my-app",
  "currentOrgSlug": "my-org"
}

Override the API URL for local development:

GITHAT_API_URL=http://localhost:4000 githat doctor

Commands deferred for v0.5+

The following are intentionally not shipped yet (higher blast radius, needs more design):

• keys delete — key revocation
• apps create / apps delete — app lifecycle management
• members list / members invite / members remove — org membership
• billing — subscription and invoice management

Requirements

• Node.js 20+

License

Proprietary — GitHat