docs

VaultKit CLI (`vkit`)

Command-line interface for VaultKit — secure, policy-driven data access control plane

The VaultKit CLI (vkit) is the primary interface for interacting with the VaultKit control plane. It enables users to request governed data access, track approvals, manage datasources, and deploy policy bundles—all while maintaining complete audit trails.

🎯 What is VaultKit CLI?

The VaultKit CLI provides command-line access to VaultKit for:

Users - Data analysts, engineers, and administrators
AI Agents - LLMs and autonomous systems requiring governed data access
Tools & Services - CI/CD pipelines, data pipelines, and automated workflows
Applications - Programmatic integration via scripting

Capability	Description
Authentication	Login, session management, identity verification
Data Requests	Submit AQL queries with automatic policy evaluation
Approval Workflows	Approve or deny access requests requiring authorization
Grant Management	Fetch data using approved, time-limited grants
Datasource Admin	Register and manage database connections (admin only)
Schema Discovery	Scan datasources and detect schema drift
Policy Deployment	Build, validate, and deploy policy bundles
Audit Queries	Search and export audit logs

Mental Model

VaultKit uses a request → policy → grant → fetch workflow:

┌──────────┐    ┌──────────┐    ┌───────┐    ┌───────┐    ┌───────────┐
│ Request  │ -> │ Policy   │ -> │ Grant │ -> │ Fetch │ -> │ Audit Log │
│ (AQL)    │    │ Eval     │    │ (JWT) │    │ Data  │    │ (Record)  │
└──────────┘    └──────────┘    └───────┘    └───────┘    └───────────┘

Key Principles:

Users request data, not queries
Policies decide what happens (allow, mask, deny, require approval)
Grants authorize execution with TTLs
FUNL executes queries safely
Everything is audited

📦 Installation

Prerequisites

Ruby 3.1 or higher
VaultKit Control Plane running and accessible

Option 1: Install from RubyGems (Recommended)

gem install vaultkitcli

Verify Installation

vkit --version
# => VaultKit CLI v0.1.0

vkit --help

⚡ Quick Start

1. Set Environment Variables

export VKIT_API_URL=http://localhost:3000

For production:

export VKIT_API_URL=https://vaultkit.company.com

2. Authenticate

vkit login --endpoint http://localhost:3000 --email analyst@company.com

You’ll receive a prompt for your password or be redirected to SSO.

3. Submit Your First Request

vkit request --aql '{
  "source_table": "customers",
  "columns": ["id", "email", "total_spend"],
  "limit": 10
}'

4. Fetch Results

If granted immediately:

vkit fetch --grant gr_abc123xyz

If approval required:

# Check status
vkit requests list --state pending

# After approval
vkit fetch --grant gr_abc123xyz

🔐 Authentication

`vkit login`

Authenticate with the VaultKit control plane.

vkit login --endpoint http://localhost:3000 --email analyst@acme.com

Options:

--endpoint — VaultKit API endpoint (can also use VKIT_API_URL)
--email — Email address for authentication

SSO Integration:

If your organization uses SSO, you’ll be redirected to your identity provider:

vkit login --endpoint https://vaultkit.company.com --email you@company.com

# Output:
# Opening browser for SSO authentication...
# ✓ Authentication successful
# Session expires: 2024-01-15 18:00:00 UTC

`vkit whoami`

Display the currently authenticated user and session information.

vkit whoami

Output:

👤 analyst@acme.com (role: analyst, org: acme)

JSON Format:

vkit whoami --format json

Output:

{
  "email": "analyst@acme.com",
  "role": "analyst",
  "org": "acme"
}

`vkit logout`

Clear stored credentials and end session.

vkit logout

🔄 Core Workflows

Workflow 1: Immediate Access (Auto-Approved)

# 1. Submit request
vkit request --aql '{
  "source_table": "public_reports",
  "columns": ["report_id", "title", "published_date"],
  "limit": 10
}'

# Output:
# ✓ Request granted immediately
# Grant ID: gr_abc123xyz
# TTL: 4 hours
# Use: vkit fetch --grant gr_abc123xyz

# 2. Fetch data
vkit fetch --grant gr_abc123xyz --format table

Workflow 2: Approval Required

# 1. Submit request
vkit request --aql '{
  "source_table": "financial_transactions",
  "columns": ["transaction_id", "amount", "customer_id"],
  "filters": [{"field": "amount", "operator": "gt", "value": 10000}]
}'

# Output:
# ⏳ Approval required
# Request ID: req_20240115_xyz789
# Approver: finance_manager
# Reason: Financial data requires manager approval
# Status: PENDING

# 2. Check status
vkit requests list --state pending

# 3. After approval, fetch data
vkit fetch --grant gr_approved_abc123

Workflow 3: Denied Access

vkit request --aql '{
  "source_table": "payment_cards",
  "columns": ["card_number", "cvv"],
  "limit": 10
}'

# Output:
# ❌ Request denied
# Reason: Direct payment card data access forbidden
# Policy: pci_dss_restrictions
# Alternative: Use tokenized_card_id field instead
# Audit ID: audit_20240115_denied_123

Command Reference

Authentication Commands

`vkit login`

Authenticate with VaultKit.

vkit login --endpoint <URL> --email <EMAIL>

Options:

--endpoint, -e — VaultKit API endpoint (default: $VKIT_API_URL)
--email — User email address
--password — Password (prompted if not provided)

Examples:

# Interactive login
vkit login --endpoint http://localhost:3000 --email analyst@company.com

# Non-interactive (CI/CD)
vkit login --endpoint https://vaultkit.company.com --email bot@company.com --password $BOT_PASSWORD

`vkit whoami`

Display current user information.

vkit whoami [--format json|table]

Examples:

vkit whoami
vkit whoami --format json

`vkit logout`

End session and clear credentials.

vkit logout

Data Request Commands

`vkit request`

Submit a governed data request using AQL.

vkit request --aql <AQL_JSON> [OPTIONS]

Options:

--aql — AQL JSON payload (inline or via STDIN)
--env — Environment (default: production)
--requester_region — Your geographic region (e.g., US, EU)
--dataset_region — Dataset’s geographic region
--requester_clearance — Clearance level: low, high, admin
--format — Output format: json, table (default: table)

Inline AQL:

vkit request \
  --aql '{"source_table":"customers","columns":["email","total_spend"],"limit":100}' \
  --requester_region EU \
  --dataset_region EU \
  --requester_clearance high

AQL via STDIN:

cat query.json | vkit request

# Or
echo '{"source_table":"orders","columns":["order_id","total"]}' | vkit request

AQL from File:

vkit request --aql "$(cat queries/customer_analysis.json)"

Possible Outcomes:

Outcome	Description	Next Step
✅ Granted	Immediate access	`vkit fetch --grant <GRANT_ID>`
⏳ Queued	Requires approval	Wait for approval, check with `vkit requests list`
❌ Denied	Policy disallows	Review policy restrictions

`vkit requests list`

View your request history.

vkit requests list [--state STATE] [--format FORMAT]

Options:

--state — Filter by state: all, pending, approved, denied (default: all)
--format — Output format: json, table (default: table)
--limit — Number of results (default: 50)

Examples:

# All requests
vkit requests list

# Only pending requests
vkit requests list --state pending

# Approved requests in JSON
vkit requests list --state approved --format json

# Last 100 requests
vkit requests list --limit 100

`vkit requests show`

Show details for a specific request.

vkit requests show <REQUEST_ID>

Example:

vkit requests show req_20240115_xyz789

Approval Commands

`vkit approval:list`

List approval requests you are authorized to act on.

vkit approval:list [--state STATE] [--format FORMAT]

Options:

--state — Filter by state: all, pending, approved, denied (default: pending)
--format — Output format: json, table (default: table)

Examples:

# Pending approvals
vkit approval:list

# All approvals you've handled
vkit approval:list --state all

# JSON output for scripting
vkit approval:list --format json

`vkit approval:approve`

Approve a pending request.

vkit approval:approve <REQUEST_ID> [--ttl SECONDS] [--notes "..."]

Options:

--ttl — Grant lifetime in seconds (default: 3600)
--notes — Approval notes (optional)

Examples:

# Basic approval
vkit approval:approve 42

# With custom TTL and notes
vkit approval:approve 42 \
  --ttl 7200 \
  --notes "Approved for Q4 analysis. Limited to aggregate data only."

`vkit approval:deny`

Deny a pending request.

vkit approval:deny <REQUEST_ID> --reason "..."

Options:

--reason — Required explanation for denial

Examples:

vkit approval:deny 42 --reason "Insufficient business justification"

vkit approval:deny 42 --reason "Request violates data minimization policy"

Data Fetch Commands

`vkit fetch`

Fetch data using a previously issued grant.

vkit fetch --grant <GRANT_REF> [--format FORMAT]

Options:

--grant, -g — Grant reference or ID (required)
--format — Output format: json, table, csv (default: table)
--output, -o — Write to file instead of STDOUT

Examples:

# Fetch and display as table
vkit fetch --grant gr_abc123xyz

# Fetch as JSON
vkit fetch --grant gr_abc123xyz --format json

# Fetch and save to CSV
vkit fetch --grant gr_abc123xyz --format csv --output results.csv

# Pipe to jq for processing
vkit fetch --grant gr_abc123xyz --format json | jq '.data[] | select(.revenue > 1000)'

Datasource Management (Admin Only)

`vkit datasource add`

vkit datasource add --id <ID> --engine <ENGINE> [OPTIONS]

Options:

--id — Unique datasource identifier (required)
--engine — Database engine: postgres, mysql, snowflake, bigquery (required)
--username — Database username
--password — Database password
--config — JSON configuration (host, port, database, etc.)
--credential-backend — Secret backend: vaultkit, vault, aws-secrets

Examples:

PostgreSQL (Built-in credential storage):

vkit datasource add \
  --id production_pg \
  --engine postgres \
  --username vaultkit_ro \
  --password $DB_PASSWORD \
  --config '{
    "host": "db.production.internal",
    "port": 5432,
    "database": "analytics",
    "ssl_mode": "require",
    "connect_timeout": 10
  }'

MySQL:

vkit datasource add \
  --id production_mysql \
  --engine mysql \
  --username app_reader \
  --password $MYSQL_PASSWORD \
  --config '{
    "host": "mysql.production.internal",
    "port": 3306,
    "database": "ecommerce",
    "ssl_mode": "REQUIRED"
  }'

`vkit datasource list`

List all registered datasources.

vkit datasource list [--format FORMAT]

Examples:

vkit datasource list
vkit datasource list --format json

`vkit datasource get`

Get details for a specific datasource.

vkit datasource get <DATASOURCE_ID>

Example:

vkit datasource get production_pg

`vkit datasource test`

Test connectivity to a datasource.

vkit datasource test <DATASOURCE_ID>

Example:

vkit datasource test production_pg

# Output:
# Testing connection to production_pg...
# ✓ Connection successful
# Engine: PostgreSQL 15.3
# Latency: 45ms

`vkit datasource remove`

Remove a datasource (admin only).

vkit datasource remove <DATASOURCE_ID> [--force]

Options:

--force — Skip confirmation prompt

Example:

vkit datasource remove old_staging_db --force

Schema Discovery Commands

`vkit scan`

Scan a datasource and detect schema drift.

vkit scan <DATASOURCE_ID> [--mode MODE]

Options:

--mode — Scan mode: diff, apply (default: diff)
--format — Output format: json, table (default: table)

Modes:

Mode	Description
`diff`	Show changes without applying (safe, read-only)
`apply`	Update baseline registry with discovered schema

Examples:

Discover Changes:

vkit scan production_pg

# Output:
# Scanning datasource: production_pg
# 
# Schema Drift Detected:
# 
# + Dataset: customers
#     + Field: phone_number (varchar) [PII] ⚠️  NEW - requires policy
#     ~ Field: email (text → varchar) [PII] ✓ Already masked
# 
# + Dataset: user_sessions
#     + Field: ip_address (inet) [PII] ⚠️  NEW - requires policy
#     + Field: user_agent (text) [INTERNAL] ⚠️  NEW - requires policy
# 
# Summary: 2 new datasets, 3 new fields, 1 modified field

Apply Changes:

vkit scan production_pg --mode apply

# Output:
# ✓ Baseline registry updated
# Next steps:
#   1. Review new fields: customers.phone_number, user_sessions.ip_address
#   2. Update policies in Git: config/policies/
#   3. Build new bundle: vkit policy bundle
#   4. Deploy bundle: vkit policy deploy

Scan All Datasources:

for ds in $(vkit datasource list --format json | jq -r '.[].id'); do
  echo "Scanning $ds..."
  vkit scan $ds
done

Policy Management Commands

`vkit policy bundle`

Compile policies and registry into a deployable bundle.

vkit policy bundle [OPTIONS]

Options:

--policies_dir — Path to policies directory (default: config/policies)
--registry_dir — Path to registry files (default: config)
--datasources_dir — Path to datasource configs (default: config/datasources)
--out — Output bundle file (default: dist/policy_bundle.json)
--org — Organization identifier (optional, defaults to logged-in user’s org)

Example:

# Using logged-in user's org
vkit policy bundle \
  --policies_dir config/policies \
  --registry_dir config \
  --datasources_dir config/datasources \
  --out dist/policy_bundle.json

# Specifying org explicitly
vkit policy bundle \
  --policies_dir config/policies \
  --registry_dir config \
  --datasources_dir config/datasources \
  --out dist/policy_bundle.json \
  --org acme

`vkit policy validate`

Validate a policy bundle without deploying.

vkit policy validate --bundle <BUNDLE_FILE>

Example:

vkit policy validate --bundle dist/policy_bundle.json

# Output:
# Validating policy bundle...
# ✓ Schema validation passed
# ✓ Policy syntax valid
# ✓ No circular dependencies
# ✓ All datasources referenced
# Bundle is valid and ready to deploy

`vkit policy deploy`

Deploy a policy bundle to the control plane.

vkit policy deploy --bundle <BUNDLE_FILE> [OPTIONS]

Options:

--bundle — Path to bundle file (required)
--org — Organization identifier (optional, defaults to logged-in user’s org)
--activate — Immediately activate bundle
--dry-run — Validate deployment without activating

Examples:

# Deploy and activate (using logged-in user's org)
vkit policy deploy \
  --bundle dist/policy_bundle.json \
  --activate

# Deploy with explicit org
vkit policy deploy \
  --bundle dist/policy_bundle.json \
  --org acme \
  --activate

# Dry run (test deployment)
vkit policy deploy \
  --bundle dist/policy_bundle.json \
  --dry-run

`vkit policy list`

List active policy bundles.

vkit policy list

`vkit policy show`

Show details of a specific policy.

vkit policy show <POLICY_ID>

Audit Commands

`vkit audit query`

Search audit logs.

vkit audit query [OPTIONS]

Options:

--user — Filter by user email
--action — Filter by action: granted, denied, pending
--dataset — Filter by dataset name
--days — Look back N days (default: 7)
--limit — Number of results (default: 100)
--format — Output format: json, table, csv

Examples:

# All queries by a user
vkit audit query --user analyst@company.com --days 30

# Denied access attempts
vkit audit query --action denied --days 7

# Access to specific dataset
vkit audit query --dataset customers --action granted

# Export to CSV
vkit audit query --user analyst@company.com --format csv --output audit_report.csv

`vkit audit export`

Export audit logs for compliance reporting.

vkit audit export --start-date <DATE> --end-date <DATE> [OPTIONS]

Options:

--start-date — Start date (YYYY-MM-DD)
--end-date — End date (YYYY-MM-DD)
--format — Output format: json, csv (default: csv)
--output — Output file path

Example:

vkit audit export \
  --start-date 2024-01-01 \
  --end-date 2024-01-31 \
  --format csv \
  --output compliance_reports/january_2024.csv

Advanced Usage

Scripting with vkit

Batch Request Processing:

#!/bin/bash
# process_requests.sh

REQUESTS=(
  '{"source_table":"customers","columns":["id","email"],"limit":100}'
  '{"source_table":"orders","columns":["order_id","total"],"limit":100}'
  '{"source_table":"products","columns":["product_id","name"],"limit":100}'
)

for aql in "${REQUESTS[@]}"; do
  echo "Processing: $aql"
  vkit request --aql "$aql" --format json | jq -r '.grant_id' >> grants.txt
done

echo "Generated grants:"
cat grants.txt

Automated Approvals (for testing):

#!/bin/bash
# auto_approve_pending.sh

PENDING=$(vkit approval:list --state pending --format json)

echo "$PENDING" | jq -r '.[].id' | while read -r request_id; do
  echo "Approving request: $request_id"
  vkit approval:approve "$request_id" --ttl 3600 --notes "Auto-approved for testing"
done

Integration with CI/CD

GitHub Actions Example:

name: Deploy VaultKit Policies

on:
  push:
    branches: [main]
    paths:
      - 'config/policies/**'
      - 'config/registry.yaml'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install vkit CLI
        run: gem install vaultkitcli
      
      - name: Authenticate
        run: |
          vkit login \
            --endpoint $ \
            --email $ \
            --password $
      
      - name: Build Policy Bundle
        run: |
          vkit policy bundle \
            --policies_dir config/policies \
            --registry_dir config \
            --out policy_bundle.json \
            --org $
      
      - name: Validate Bundle
        run: vkit policy validate --bundle policy_bundle.json
      
      - name: Deploy Bundle
        run: |
          vkit policy deploy \
            --bundle policy_bundle.json \
            --org $ \
            --activate

Using jq for Advanced Filtering

Extract specific fields:

vkit requests list --format json | jq '.[] | select(.state == "approved") | {id, dataset, requester}'

Count requests by state:

vkit requests list --format json | jq 'group_by(.state) | map({state: .[0].state, count: length})'

Find high-value transactions:

vkit fetch --grant gr_abc123 --format json | jq '.data[] | select(.amount > 10000)'

Troubleshooting

Common Issues

Authentication Failed

Problem:

Error: Authentication failed (401 Unauthorized)

Solutions:

# 1. Check endpoint
echo $VKIT_API_URL

# 2. Re-authenticate
vkit logout
vkit login --endpoint http://localhost:3000 --email you@company.com

# 3. Verify credentials
vkit whoami

Connection Refused

Problem:

Error: Connection refused - connect(2) for "localhost" port 3000

Solutions:

# 1. Check if control plane is running
curl http://localhost:3000/health

# 2. Verify Docker containers
cd infra
docker compose ps

# 3. Start services
docker compose up

Grant Expired

Problem:

Error: Grant has expired
Grant ID: gr_abc123xyz
Expired at: 2024-01-15 12:00:00 UTC

Solutions:

# 1. Request new grant
vkit request --aql '{"source_table":"customers",...}'

# 2. Request longer TTL (if approval required)
vkit request --aql '{...}' --ttl 7200

Policy Denial

Problem:

❌ Request denied
Reason: Cross-region PII access forbidden
Policy: gdpr_protection

Solutions:

Review policy restrictions
Request approval if available
Modify query to exclude restricted fields
Contact admin to update policies

Debug Mode

Enable verbose logging:

# Set debug environment variable
export VKIT_DEBUG=true

# Run command
vkit request --aql '{...}'

# Output includes:
# - HTTP request/response details
# - Policy evaluation trace
# - Timing information

Health Check

Verify CLI and control plane connectivity:

# Check CLI version
vkit --version

# Check control plane health
curl $VKIT_API_URL/health

# Test authentication
vkit whoami

Contributing

We welcome contributions to the VaultKit CLI!

Development Setup

# Clone repository
git clone https://github.com/yourorg/vaultkit-cli.git
cd vaultkit-cli

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Run CLI locally
bundle exec bin/vkit --help

Running Tests

# Unit tests
bundle exec rspec spec/unit

# Integration tests (requires running control plane)
bundle exec rspec spec/integration

# All tests
bundle exec rspec

Code Style

# Run RuboCop
bundle exec rubocop

# Auto-fix issues
bundle exec rubocop -a

Additional Resources

Main Repository: github.com/ndbaba1/vaultkitcli.git
Documentation: docs.vaultkit.io
AQL Specification: docs.vaultkit.io/aql
Policy Reference: docs.vaultkit.io/policies
API Documentation: docs.vaultkit.io/api

License

VaultKit CLI is licensed under the Apache License 2.0. See LICENSE for details.

Built with ❤️ by the VaultKit team

This site is open source. Improve this page.

docs

VaultKit CLI (vkit)

📋 Table of Contents

🎯 What is VaultKit CLI?

Mental Model

📦 Installation

Prerequisites

Option 1: Install from RubyGems (Recommended)

Verify Installation

⚡ Quick Start

1. Set Environment Variables

2. Authenticate

3. Submit Your First Request

4. Fetch Results

🔐 Authentication

vkit login

vkit whoami

vkit logout

🔄 Core Workflows

Workflow 1: Immediate Access (Auto-Approved)

Workflow 2: Approval Required

Workflow 3: Denied Access

Command Reference

Authentication Commands

vkit login

vkit whoami

vkit logout

Data Request Commands

vkit request

vkit requests list

vkit requests show

Approval Commands

vkit approval:list

vkit approval:approve

vkit approval:deny

Data Fetch Commands

vkit fetch

Datasource Management (Admin Only)

vkit datasource add

vkit datasource list

vkit datasource get

vkit datasource test

vkit datasource remove

Schema Discovery Commands

vkit scan

Policy Management Commands

vkit policy bundle

vkit policy validate

vkit policy deploy

vkit policy list

vkit policy show

Audit Commands

vkit audit query

vkit audit export

Advanced Usage

Scripting with vkit

Integration with CI/CD

Using jq for Advanced Filtering

Troubleshooting

Common Issues

Authentication Failed

Connection Refused

Grant Expired

Policy Denial

Debug Mode

Health Check

Contributing

Development Setup

Running Tests

Code Style

Additional Resources

License

VaultKit CLI (`vkit`)

`vkit login`

`vkit whoami`

`vkit logout`

`vkit login`

`vkit whoami`

`vkit logout`

`vkit request`

`vkit requests list`

`vkit requests show`

`vkit approval:list`

`vkit approval:approve`

`vkit approval:deny`

`vkit fetch`

`vkit datasource add`

`vkit datasource list`

`vkit datasource get`

`vkit datasource test`

`vkit datasource remove`

`vkit scan`

`vkit policy bundle`

`vkit policy validate`

`vkit policy deploy`

`vkit policy list`

`vkit policy show`

`vkit audit query`

`vkit audit export`