cli

🚀 Quick Start

curl -fsSL https://kest.dev/install.sh | sh

For the latest released CLI, use the install script above. If you need the current repo source instead of the latest release:

git clone https://github.com/kest-labs/kest.git
cd kest/cli
go build -o ~/.local/bin/kest .

kest init                                                    # Initialize project
kest get /api/users -a "status==200"                         # Test an endpoint
kest post /api/login -d '{"user":"admin"}' -c "token=data.token"  # Capture token
kest get /api/profile -H "Authorization: Bearer {{token}}"   # Use it instantly

Every request is auto-recorded. Variables chain automatically. No copy-paste.

🔄 Sync To Kest Platform

Kest CLI can upload local API history back to the Kest Web Console. The recommended flow is:

1. Open the project in the Web Console.
2. Open the project detail page.
3. In the CLI Sync card, click Generate CLI Token.
4. Copy the one-line setup command or run:

kest sync config \
  --platform-url "https://api.kest.dev/v1" \
  --platform-token "kest_pat_..." \
  --project-id "12"

This writes platform_url, platform_token, and platform_project_id into .kest/config.yaml when run inside a Kest project.

You can verify the saved config:

kest config list

Preview the upload first:

kest sync push --dry-run

Then upload your local history-derived specs:

kest sync push

CLI uploads use a project-scoped token, not your OpenAI sk-... key.

What gets uploaded:

• API method + path inferred from local history
• summary / version / simple response schema stubs
• sanitized examples derived from request history

What is redacted before storage:

• Authorization, Cookie, X-API-Key and similar sensitive headers
• common secret-shaped JSON fields such as password, token, secret, api_key, client_secret

⚡ Why Kest?

Kest is designed for Vibe Coding — the workflow where you and an AI copilot build together in the terminal.

The Vibe Coding loop: kest → AI sees output → AI suggests fix → kest replay → verified. All in one terminal.

🧠 AI-Powered

Kest uses your local request history as context for AI — something no other tool can do.

kest why                           # AI diagnoses why your last request failed
kest suggest                       # AI suggests the next logical API call
kest explain 42                    # AI explains what record #42 does
kest review auth.flow.md           # AI audits your flow for security gaps
kest gen "test user registration"  # AI generates a complete .flow.md

kest config set ai_key sk-xxx      # Supports OpenAI, Azure, any compatible API
kest config set ai_model gpt-4o

📝 Markdown Flow — Documentation IS Your Test Suite

Write tests as .flow.md files — readable by humans, executable by Kest, reviewable in PRs.

```step
@id login
POST /api/login
Content-Type: application/json
{"user": "admin", "pass": "secret"}

[Captures]
token = data.token

[Asserts]
status == 200
```

```step
@id profile
GET /api/profile
Authorization: Bearer {{token}}

[Asserts]
status == 200
body.user == "admin"
```

$ kest run login.flow.md

  ▶ login POST /api/login
    ✅ 200 (142ms)

  ▶ profile GET /api/profile
    ✅ 200 (89ms)

╭──────────────────────────────────────────────────╮
│                 TEST SUMMARY                      │
├──────────────────────────────────────────────────┤
│ ✓ [POST] /api/login                  142ms │
│ ✓ [GET]  /api/profile                  89ms │
├──────────────────────────────────────────────────┤
│ Total: 2  │  Passed: 2  │  Time: 231ms │
╰──────────────────────────────────────────────────╯

🔥 More Features

Mock Server — zero config, from your history

kest mock --port 8080
# Serves recorded responses automatically
# GET  /api/users → 200    POST /api/login → 200

Snapshot Testing — like Jest, but for APIs

kest snap /api/users              # Save snapshot
kest snap /api/users --verify     # ❌ 'role' field changed!
kest snap /api/users --update     # Accept new snapshot

Replay & Diff — instant regression detection

kest replay last --diff
# - "role": "admin"
# + "role": "superadmin"  ← changed!

File Watch — TDD for APIs

kest watch login.flow.md
# [14:03:21] ✅ All 4 steps passed (1.2s)
# [14:03:35] 📝 File changed, re-running...
# [14:03:36] ✅ All 4 steps passed (0.9s)

gRPC + TLS

kest grpc localhost:50051 pkg.Service/Method -p app.proto -d '{}'
kest grpc api.example.com:443 pkg.Service/Method --tls --cert ca.pem

SSE / LLM Streaming

kest post /v1/chat/completions -d '{"stream":true, ...}' --stream

🏆 Comparison

📖 Command Reference

kest get /api/users                              # GET
kest post /api/users -d '{"name":"Alice"}'       # POST with JSON body
kest put /api/users/1 -d '{"name":"Bob"}'        # PUT
kest delete /api/users/1                         # DELETE
kest post /api/upload -d @file.json              # Body from file

# Flags
-H "Key: Value"       # Header
-q "key=value"        # Query param
-c "var=json.path"    # Capture variable
-a "status==200"      # Assertion
-v                    # Verbose (show headers)
--max-time 5000       # Timeout (ms)
--retry 3             # Retry count
--retry-delay 1000    # Retry delay (ms)
--stream              # SSE streaming
--var key=value       # Set variable

kest history                # Recent records
kest history -n 50          # Last 50
kest show last              # Full request/response details
kest show 42                # Specific record
kest diff 100 last          # Compare two records
kest replay last --diff     # Re-execute and compare

kest run login.flow.md                  # Run flow file
kest run login.flow.md --var key=val    # With variables
kest run tests/ --parallel --jobs 8     # Parallel execution
kest watch login.flow.md                # Auto-rerun on change
kest snap /api/users                    # Save snapshot
kest snap /api/users --verify           # Verify against snapshot
kest mock --port 8080                   # Mock server from history

kest init                   # Initialize project
kest config set ai_key sk-xxx
kest config set ai_model gpt-4o
kest env set staging        # Switch environment
kest vars                   # List captured variables
kest completion zsh         # Shell completion

🏗 Architecture

Terminal                              Local Storage
┌──────────────────┐                 ┌──────────────┐
│ kest get /users  │──auto-record──→│ SQLite DB     │
│ kest post /login │──capture var──→│ Variables     │
│ kest run flow.md │──assertions──→ │ History       │
└──────────────────┘                 └──────┬───────┘
                                            │
                                   ┌────────▼────────┐
                                   │ AI Engine        │
                                   │ why · suggest    │
                                   │ explain · review │
                                   └─────────────────┘

100% local. No cloud. No account. No telemetry. Your data never leaves your machine.

🤝 Contributing

git clone https://github.com/kest-labs/kest.git
cd kest/cli
go build -o kest .
go test ./...

See VISION.md for project philosophy. PRs welcome!