CLI

The Istek CLI allows you to run API tests, manage collections, and integrate Istek into your CI/CD pipelines from the terminal.

Installation

From crates.io

cargo install istek-cli

Homebrew (macOS)

brew install istekapp/tap/istek-cli

Scoop (Windows)

scoop bucket add istekapp https://github.com/istekapp/scoop-bucket
scoop install istek-cli

From Source

git clone https://github.com/istekapp/istek-cli
cd istek-cli
cargo install --path .

Prerequisites

The Istek desktop application must be running for the CLI to work. The CLI communicates with the Internal REST API that runs alongside the desktop app on port 47835.

Configuration

Environment Variables

Variable	Description	Default
ISTEK_API_URL	API server URL	http://localhost:47835
ISTEK_WORKSPACE_ID	Default workspace ID	-

export ISTEK_API_URL="http://localhost:47835"
export ISTEK_WORKSPACE_ID="your-workspace-id"

Global Options

All commands support these options:

Option	Short	Description
--api-url		Override API server URL
--workspace	-w	Specify workspace ID
--output	-o	Output format: table (default) or json

Commands

Workspaces

List Workspaces

istek workspaces list

Output:

┌──────────────────────────────────────┬─────────────┬─────────┬───────────────────┐
│ ID                                   │ Name        │ Default │ Created           │
├──────────────────────────────────────┼─────────────┼─────────┼───────────────────┤
│ ws_abc123                            │ My Project  │ Yes     │ 2024-01-15 10:30  │
│ ws_def456                            │ Work APIs   │ No      │ 2024-01-20 14:45  │
└──────────────────────────────────────┴─────────────┴─────────┴───────────────────┘

Show Workspace Details

istek workspaces show <WORKSPACE_ID>

Collections

List Collections

istek -w <WORKSPACE_ID> collections list

Show Collection Details

istek -w <WORKSPACE_ID> collections show <COLLECTION_ID>

Shows collection structure including folders and requests:

Collection: User API
ID: col_xyz789
Requests: 12
Folders: 3

Requests:
  1. GET Health Check - {{API_URL}}/health

Folder: Authentication:
  1. POST Login - {{API_URL}}/auth/login
  2. POST Register - {{API_URL}}/auth/register
  3. POST Refresh Token - {{API_URL}}/auth/refresh

Test Runner

The CLI test runner executes collection tests with real-time output.

Run All Tests

istek -w <WORKSPACE_ID> test <COLLECTION_ID>

Test Options

Option	Short	Default	Description
--folder	-f	-	Run tests only in specified folder
--stop-on-failure	-s	false	Stop on first failure
--delay	-d	0	Delay between requests (ms)

Run Tests in a Folder

istek -w <WORKSPACE_ID> test <COLLECTION_ID> --folder <FOLDER_ID>

Stop on First Failure

istek -w <WORKSPACE_ID> test <COLLECTION_ID> --stop-on-failure

Add Delay Between Requests

istek -w <WORKSPACE_ID> test <COLLECTION_ID> --delay 500

Test Output

The test runner displays real-time progress with colored output:

Collection: User API Tests
Testing: 5 requests

  1. ✓ GET Health Check [200] 23ms
  2. ✓ POST Create User [201] 145ms (3/3)
  3. ✗ GET Get User [404] 12ms (0/1)
  4. ✓ PUT Update User [200] 89ms (2/2)
  5. ✓ DELETE Delete User [204] 34ms

Summary: 4 passed | 1 failed | 0 errors | 5 total in 303ms

Failures:

  Request: Get User
    ✗ Status code is 200
      Expected: 200
      Actual: 404

Output Legend

• ✓ - Test passed
• ✗ - Test failed
• ! - Request error
• [200] - HTTP status code
• 45ms - Response time
• (3/3) - Assertions passed/total

Exit Codes

Code	Description
0	All tests passed
1	One or more tests failed or errored

JSON Output

Use -o json for machine-readable output:

# List workspaces as JSON
istek -o json workspaces list

# Test results as JSON
istek -w <WORKSPACE_ID> -o json test <COLLECTION_ID>

JSON test output includes the full test summary:

{
  "runId": "run_abc123",
  "name": "User API Tests",
  "total": 5,
  "passed": 4,
  "failed": 1,
  "errors": 0,
  "totalTime": 303,
  "results": [
    {
      "requestId": "req_001",
      "requestName": "Health Check",
      "method": "GET",
      "status": "passed",
      "responseStatus": 200,
      "responseTime": 23,
      "assertions": []
    }
  ]
}

CI/CD Integration

GitHub Actions

name: API Tests

on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Istek CLI
        run: cargo install istek-cli
        
      - name: Run API Tests
        env:
          ISTEK_API_URL: ${{ secrets.ISTEK_API_URL }}
          ISTEK_WORKSPACE_ID: ${{ secrets.ISTEK_WORKSPACE_ID }}
        run: |
          istek test ${{ vars.COLLECTION_ID }} --stop-on-failure

GitLab CI

api-tests:
  stage: test
  image: rust:latest
  script:
    - cargo install istek-cli
    - istek -w $ISTEK_WORKSPACE_ID test $COLLECTION_ID
  variables:
    ISTEK_API_URL: $ISTEK_API_URL
    ISTEK_WORKSPACE_ID: $ISTEK_WORKSPACE_ID

Jenkins

pipeline {
    agent any
    
    environment {
        ISTEK_API_URL = credentials('istek-api-url')
        ISTEK_WORKSPACE_ID = credentials('istek-workspace-id')
    }
    
    stages {
        stage('API Tests') {
            steps {
                sh 'cargo install istek-cli'
                sh 'istek test ${COLLECTION_ID} --stop-on-failure'
            }
        }
    }
}

Tips

Use Environment Variables

Set ISTEK_WORKSPACE_ID to avoid passing -w on every command.

JSON for Scripts

Use -o json when parsing output in scripts or CI pipelines.

Folder Testing

Use --folder to run a subset of tests during development.

Delay for Rate Limits

Use --delay when testing APIs with rate limiting.