Getting Started

Go from zero to your first scan in under 5 minutes. No signup required, no credit card, no configuration.

Prerequisites

TK-TIS CLI tools require Node.js 18.0.0 or later. The core tools (tk-scan, tk-guard, tk-pulse) have zero external dependencies and use only Node.js built-in modules.

Check your Node.js version:

node --version
# v18.0.0 or later required

Installation

Global Installation (recommended)

Install all five CLI tools globally so they are available as commands anywhere:

# Install all CLI tools
npm install -g @tk-tis/tk-scan @tk-tis/tk-guard @tk-tis/tk-pulse

# For E2E testing and visual regression (requires Playwright)
npm install -g @tk-tis/tk-flow @tk-tis/tk-eye
npx playwright install chromium

Run Without Installing

You can run any tool directly using npx without installing anything:

npx @tk-tis/tk-scan https://your-site.com
npx @tk-tis/tk-guard https://your-site.com
npx @tk-tis/tk-pulse https://your-site.com

Project-Level Installation

Add tools as dev dependencies in your project:

npm install --save-dev @tk-tis/tk-scan @tk-tis/tk-guard @tk-tis/tk-pulse

Then add scripts to your package.json:

{
  "scripts": {
    "test:scan": "tk-scan https://your-site.com --threshold 80",
    "test:guard": "tk-guard https://your-site.com --deep",
    "test:perf": "tk-pulse https://your-site.com --threshold 70",
    "test:all": "npm run test:scan && npm run test:guard && npm run test:perf"
  }
}

Your First Scan

Run tk-scan against any website to get a comprehensive health report:

tk-scan https://your-site.com

You will see output like this:

===================================================
  TK-Scan v1.0 — https://your-site.com
===================================================

  Score:  92/100  PASS  (threshold: 80)
  Time:   1240ms

  ROUTES
  ─────────────────────────────────────────────────
  + 200  /                              340ms  14280B

  SECURITY HEADERS
  ─────────────────────────────────────────────────
  + HSTS                       max-age=31536000; includeSubDomains
  + X-Frame-Options            DENY
  + X-Content-Type-Options     nosniff
  + CSP                        default-src 'self'...
  x Referrer-Policy            MISSING
  + Permissions-Policy         camera=(), microphone=()

  CORS
  ─────────────────────────────────────────────────
  + No CORS issues detected

  SEO
  ─────────────────────────────────────────────────
  + <title> tag present

Understanding Results

Scores and Thresholds

Each scan produces a score from 0 to 100. The default pass threshold is 80. The CLI exits with code 0 for PASS and 1 for FAIL, making it easy to integrate into CI/CD pipelines.

What Is Checked

tk-scan evaluates multiple categories:

• HTTP Status — Every route returns a 2xx or 3xx status code
• Response Time — Flags slow responses (over 1s yellow, over 3s red)
• Body Size — Flags empty pages (under 100 characters)
• App Crash Detection — Detects error boundaries and ChunkLoadError
• Security Headers — HSTS, X-Frame-Options, X-Content-Type-Options, CSP, Referrer-Policy, Permissions-Policy
• Stale URLs — Detects references to old API versions in HTML/JS
• SEO — Checks for noindex meta tags and title tags
• CORS — OPTIONS preflight check for wildcard origins

JSON Output

Add --json to get machine-readable output for programmatic processing:

tk-scan https://your-site.com --json | jq '.score'

Setting Up the Dashboard

The TK-TIS web dashboard gives you a visual interface for managing projects, viewing historical results, and configuring alerts.

1. Navigate to tk-tis.pages.dev/dashboard/
2. Create an account or sign in
3. Add your first project by entering the URL you want to monitor
4. Generate an API key from the Settings page
5. Use the API key with the --report flag to send CLI results to the dashboard

# Report scan results to your dashboard
tk-scan https://your-site.com \
  --report https://htk-cloud-v4.enzu-agent.workers.dev/api/test-engine/external-report

See the Dashboard Guide for full details.

CI/CD Integration

TK-TIS tools are designed for CI/CD from day one. Every tool supports:

• --json for machine-readable output
• --no-color for clean log files
• Non-zero exit codes on failure for pipeline gating
• --threshold for custom pass/fail criteria

Here is a minimal GitHub Actions example:

name: TK-TIS Quality Gate
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run health check
        run: npx @tk-tis/tk-scan https://your-site.com --threshold 80

      - name: Run security scan
        run: npx @tk-tis/tk-guard https://your-site.com

      - name: Run performance check
        run: npx @tk-tis/tk-pulse https://your-site.com --threshold 70

See the full CI/CD Integration Guide for GitHub Actions, GitLab CI, and webhook setup.

Next Steps