tk-pulse Free
Performance measurement CLI tool. Measures TTFB, load time, response size, and API latency. Calculates a speed score with letter grade. Zero dependencies.
bash
npm install -g @tk-tis/tk-pulse
# or run directly
npx @tk-tis/tk-pulse https://your-site.comUsage
bash
# Basic performance measurement
tk-pulse https://example.com
# Run 5 times and show averaged results
tk-pulse https://example.com --repeat 5
# Also measure an API endpoint
tk-pulse https://example.com --api-url https://api.example.com/health
# JSON output
tk-pulse https://example.com --json
# Set minimum score threshold (exit code 1 if below)
tk-pulse https://example.com --threshold 80
# Combine options
tk-pulse https://example.com -n 3 --api-url https://api.example.com/v1/status --json
# Disable colors
tk-pulse https://example.com --no-color
# Report to HTK-Cloud
tk-pulse https://example.com --report https://htk-cloud-v4.enzu-agent.workers.dev/api/pulseOptions
| Flag | Description | Default |
|---|---|---|
--repeat N, -n N |
Run N times and show averaged results | 1 |
--api-url <url> |
Also measure an API endpoint's response time | — |
--json |
Output results as JSON | false |
--threshold <score> |
Minimum acceptable score (0-100). Exits with code 1 if below | — |
--no-color |
Disable ANSI color codes | false |
--report <url> |
Send results to an HTK-Cloud endpoint | — |
-v, --version |
Show version | — |
-h, --help |
Show help | — |
Score Formula
The speed score is calculated from four metrics, each worth up to 25 points:
| Metric | Excellent (25) | Good (15) | Fair (5) | Poor (0) |
|---|---|---|---|---|
| TTFB | < 200ms | < 500ms | < 1000ms | >= 1000ms |
| Load Time | < 1000ms | < 2000ms | < 3000ms | >= 3000ms |
| Response Size | < 50 KB | < 200 KB | < 500 KB | >= 500 KB |
| API Response | < 100ms | < 300ms | < 500ms | >= 500ms |
Note
When no API endpoint is specified with --api-url, the score is calculated from the 75-point maximum (TTFB + Load + Size) and scaled to a 100-point scale.
Grades
| Grade | Score Range |
|---|---|
| A | 90 – 100 |
| B | 80 – 89 |
| C | 60 – 79 |
| D | 40 – 59 |
| F | 0 – 39 |
JSON Output
json
{
"url": "https://example.com",
"ttfb_ms": 142,
"load_ms": 387,
"size_bytes": 12480,
"status_code": 200,
"api_url": "https://api.example.com/health",
"api_response_ms": 85,
"api_status_code": 200,
"score": 100,
"grade": "A",
"timestamp": "2026-03-31T10:00:00.000Z"
}Repeated Measurements
Use --repeat N (or -n N) to run multiple measurements and get averaged results. This produces more reliable data by smoothing out network variance:
bash
# Run 10 measurements for reliable averages
tk-pulse https://example.com -n 10 --jsonExit Codes
| Code | Meaning |
|---|---|
0 | Success. If --threshold is set, score is above the threshold |
1 | Failure. Score is below threshold, or a measurement error occurred |
Programmatic Usage
javascript
const { measure, measureRepeat } = require('@tk-tis/tk-pulse');
// Single measurement
const result = await measure('https://example.com', {
apiUrl: 'https://api.example.com/health'
});
console.log(result.score, result.grade); // 100, "A"
// Averaged measurements (5 runs)
const avg = await measureRepeat('https://example.com', 5);
console.log(avg.ttfb_ms); // 142 (averaged)
console.log(avg.load_ms); // 387 (averaged)
console.log(avg.score); // 95
console.log(avg.grade); // "A"Cloud Reporter
javascript
const { report } = require('@tk-tis/tk-pulse/src/reporter');
const result = await measure('https://example.com');
await report('https://htk-cloud-v4.enzu-agent.workers.dev/api/pulse', result);