The CA certificate CLI manages SSL/TLS certificate authority operations for intercepting HTTPS traffic. Installing the CA certificate allows Stoobly to decrypt and inspect HTTPS requests for recording, mocking, and testing.
Understanding CA Certificates
Q: What is a CA certificate?
A: A CA (Certificate Authority) certificate is a root certificate that allows Stoobly to create valid SSL certificates for intercepting HTTPS traffic. It enables the proxy to decrypt, inspect, and re-encrypt HTTPS requests.
Example:
# Install CA certificate to enable HTTPS interceptionstoobly-agentca-certinstall
Q: Why do I need to install a CA certificate?
A: Installing the CA certificate allows Stoobly to intercept HTTPS traffic. Without it, you can only record and mock HTTP (non-encrypted) requests.
Example:
# Without CA cert: Only HTTP worksstoobly-agentrecordhttp://api.example.com/users# With CA cert: Both HTTP and HTTPS workstoobly-agentca-certinstallstoobly-agentrecordhttps://api.example.com/users# Now works!
Q: Is it safe to install the CA certificate?
A: Yes, the CA certificate is only installed on your local machine and is only trusted by your system. It's used solely for local development and testing. Remove it when done with ca-cert uninstall.
Example:
Installing CA Certificate
Q: How do I install the CA certificate?
A: Use ca-cert install to install the certificate authority certificate on your system.
Example:
Q: Where does the CA certificate get installed?
A: The CA certificate is installed in your system's trusted certificate store. The location varies by operating system:
macOS: Keychain Access
Linux: /usr/local/share/ca-certificates/ or system store
Windows: Certificate Manager
Example:
Q: Do I need sudo/admin privileges to install the CA certificate?
A: Yes, installing system certificates typically requires administrative privileges.
Example:
Q: How do I install the CA certificate to a custom directory?
A: Use the --ca-certs-dir-path option to specify where the CA certificate files are stored.
Example:
Q: What happens during CA certificate installation?
A: The installation process creates the CA certificate (if not exists), adds it to your system's trust store, and configures it to be trusted for SSL/TLS connections.
Example:
Viewing Certificate Path
Q: How do I find the path to the CA certificate file?
A: Use ca-cert show with the --format option to output the path to the certificate file in the specified format.
Example:
Q: What certificate formats are available?
A: The show command supports three formats: cer, p12, and pem. Each format has different use cases.
Example:
Q: How do I use the certificate path in scripts?
A: The show command outputs only the path to stdout, making it ideal for scripting and command substitution.
Example:
Q: What happens if the certificate doesn't exist?
A: The show command will output an error message and exit with a non-zero status if the certificate file is not found.
Example:
Q: How do I specify a custom CA certs directory?
A: Use the --ca-certs-dir-path option to search for certificates in a custom directory.
Example:
Q: When should I use the show command?
A: Use ca-cert show when you need the certificate path for manual import (e.g., Firefox), scripting, or when referencing the certificate in other tools.
Example:
Creating SSL Certificates
Q: How do I create an SSL certificate for a hostname?
A: Use ca-cert mkcert with the hostname to generate a signed certificate.
Example:
Q: How do I create certificates for multiple hostnames?
A: Run mkcert for each hostname you need to intercept.
Example:
Q: How do I create a wildcard certificate?
A: Use wildcard notation with the asterisk (*) for the subdomain.
Example:
Q: Where are the generated certificates stored?
A: Certificates are stored in the certs directory (default: ~/.stoobly/certs/).
Example:
Q: How do I specify a custom output directory for certificates?
A: Use the --certs-dir-path option to specify where certificates should be saved.
Example:
Q: How do I specify a custom CA certs directory?
A: Use the --ca-certs-dir-path option to use a different CA certificate for signing.
Example:
Uninstalling CA Certificate
Q: How do I uninstall the CA certificate?
A: Use ca-cert uninstall to remove the certificate from your system (coming soon).
Example:
Q: How do I manually remove the CA certificate?
A: Manually remove it from your system's certificate store until uninstall is implemented.
Example:
Workflow Integration
Q: When should I install the CA certificate?
A: Install it before recording or testing HTTPS traffic. It's typically done once per machine during initial setup.
Example:
Q: How do I use CA certificates with scaffold workflows?
A: The scaffold workflow automatically prompts for CA certificate installation when needed.
Example:
Q: How do I verify the CA certificate is installed?
A: Try recording HTTPS traffic. If it works without certificate errors, the CA cert is properly installed.
Example:
Troubleshooting
Q: What do I do if HTTPS recording fails?
A: Ensure the CA certificate is installed and trusted by your system.
Example:
Q: What if I get SSL verification errors?
A: The CA certificate may not be properly trusted. Reinstall or manually verify in your system's certificate store.
Example:
Q: How do I handle multiple CA certificates?
A: Use different --ca-certs-dir-path for different projects or environments.
Example:
Q: What do I do if certificate installation fails?
A: Check for permission issues, ensure the directory exists, and verify you have admin privileges.
Example:
Browser Configuration
Q: Do I need to configure my browser after installing the CA certificate?
A: Most browsers use the system certificate store, but some (like Firefox) use their own. You may need to import the certificate manually.
Example:
Q: How do I test if my browser trusts the CA certificate?
A: Start Stoobly proxy and visit an HTTPS site through it. If no certificate warning appears, it's working.
Example:
Team Collaboration
Q: Do team members need to install the CA certificate?
A: Yes, each team member needs to install the CA certificate on their machine to intercept HTTPS traffic.
Example:
Q: Can I share CA certificate files with my team?
A: You can share the CA certificate files, but each team member still needs to install them on their system.
Example:
Q: Should CA certificates be committed to version control?
A: Generally no, as they're generated per machine. However, for team consistency, you can share a common CA certificate by committing it.
Example:
CI/CD Integration
Q: How do I handle CA certificates in CI/CD?
A: Install the CA certificate in the CI environment before running tests.
Example:
Q: How do I use certificates in Docker containers?
A: Mount the CA certificate directory and install it in the container.
Example:
Security Considerations
Q: Is the CA certificate secure?
A: The CA certificate is only trusted on your local machine. However, anyone with access to the private key could intercept your HTTPS traffic, so protect the certificate files.
Example:
Q: Should I use the same CA certificate in production?
A: No! The CA certificate is for local development and testing only. Never use it in production environments.
Example:
Q: How do I rotate CA certificates?
A: Delete old certificates and generate new ones.
Example:
Quick Reference
Q: What are the most common ca-cert commands?
A: Here's a quick reference of frequently used commands:
Example:
Complete Setup Example
Q: What's the complete workflow for setting up CA certificates?
A: Install CA cert → Create host certificates → Configure proxy → Test HTTPS.
Example:
Platform-Specific Notes
Q: Are there any macOS-specific considerations?
A: On macOS, you may need to approve the certificate in Keychain Access and restart your browser.
Example:
Q: Are there any Linux-specific considerations?
A: On Linux, you may need to update the certificate store after installation.
Example:
Q: Are there any Windows-specific considerations?
A: On Windows, you may need to run the command prompt as Administrator.
# Install for testing
stoobly-agent ca-cert install
# When done, uninstall
stoobly-agent ca-cert uninstall
stoobly-agent ca-cert install
# Install CA cert
stoobly-agent ca-cert install
# On macOS, verify in Keychain Access
open -a "Keychain Access"
# Search for "stoobly" or "mitmproxy"
# On Linux, check system certificates
ls /usr/local/share/ca-certificates/
# May prompt for password
stoobly-agent ca-cert install
# On Linux, might need sudo
sudo stoobly-agent ca-cert install
# Install from custom directory
stoobly-agent ca-cert install --ca-certs-dir-path /path/to/custom/ca-certs
stoobly-agent ca-cert install
# Output:
# Generating CA certificate...
# Installing CA certificate to system trust store...
# CA certificate installed successfully!
# Show path to PEM format certificate
stoobly-agent ca-cert show --format pem
# Output: /home/user/.stoobly/ca_certs/mitmproxy-ca-cert.pem
# Show path to CER format certificate
stoobly-agent ca-cert show --format cer
# Output: /home/user/.stoobly/ca_certs/mitmproxy-ca-cert.cer
# Show path to P12 format certificate
stoobly-agent ca-cert show --format p12
# Output: /home/user/.stoobly/ca_certs/mitmproxy-ca-cert.p12
# PEM format (most common, used by many tools)
stoobly-agent ca-cert show --format pem
# CER format (common on Windows/macOS)
stoobly-agent ca-cert show --format cer
# P12 format (PKCS#12, contains private key)
stoobly-agent ca-cert show --format p12
# Use in a script to copy certificate
CERT_PATH=$(stoobly-agent ca-cert show --format pem)
cp "$CERT_PATH" /path/to/destination/
# Use with command substitution in Linux installation
sudo cp $(stoobly-agent ca-cert show --format pem) /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
sudo update-ca-certificates
# Use in environment variable
export CA_CERT_PATH=$(stoobly-agent ca-cert show --format pem)
echo "Certificate at: $CA_CERT_PATH"
stoobly-agent ca-cert show --format pem
# Output (if not found):
# Certificate file not found: /path/to/cert.pem
# Run 'stoobly-agent ca-cert install' to generate certificates.
# Check exit status
echo $?
# Output: 1 (error)
# Show certificate from custom directory
stoobly-agent ca-cert show --format pem --ca-certs-dir-path /path/to/custom/ca-certs
# Use in script with custom path
CERT_PATH=$(stoobly-agent ca-cert show --format pem --ca-certs-dir-path ~/.custom-stoobly/ca_certs)
# For Firefox manual import
FIREFOX_CERT=$(stoobly-agent ca-cert show --format pem)
# Then import $FIREFOX_CERT in Firefox settings
# For automated deployment scripts
CERT_PATH=$(stoobly-agent ca-cert show --format pem)
scp "$CERT_PATH" server:/tmp/stoobly-ca.pem
# For verification
if stoobly-agent ca-cert show --format pem > /dev/null 2>&1; then
echo "Certificate exists"
else
echo "Certificate not found, installing..."
stoobly-agent ca-cert install
fi
# Create certificate for a domain
stoobly-agent ca-cert mkcert api.example.com
# Uninstall CA certificate
stoobly-agent ca-cert uninstall
# Output: Not yet implemented. Stay tuned!
# macOS: Use Keychain Access
# 1. Open Keychain Access
# 2. Search for "stoobly" or "mitmproxy"
# 3. Delete the certificate
# Linux: Remove from certificate directory
sudo rm /usr/local/share/ca-certificates/stoobly-ca.crt
sudo update-ca-certificates
# Windows: Use Certificate Manager (certmgr.msc)
# 1. Open Certificate Manager
# 2. Navigate to Trusted Root Certification Authorities
# 3. Find and delete the Stoobly/mitmproxy certificate
# Initial setup
stoobly-agent ca-cert install
# Now you can record HTTPS
stoobly-agent run --intercept --intercept-mode record
# Start scaffold workflow
stoobly-agent scaffold workflow up record --app-dir-path ./my-app
# Prompt: Installing CA certificate is required for recording requests, continue? (y/N)
# Or skip prompt with environment variable
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y
stoobly-agent scaffold workflow up record --app-dir-path ./my-app
# Or using Makefile
make -f .stoobly/services/.Makefile record
# Test HTTPS recording
stoobly-agent run --intercept --intercept-mode record
# In another terminal, try recording HTTPS
stoobly-agent record https://api.example.com/test
# If successful, CA cert is working
# Reinstall CA certificate
stoobly-agent ca-cert install
# Check if certificate exists
ls ~/.mitmproxy/
# Should see: mitmproxy-ca.pem, mitmproxy-ca-cert.pem
# Try recording again
stoobly-agent record https://api.example.com/users
# Reinstall
stoobly-agent ca-cert install
# On macOS, verify trust settings in Keychain Access
open -a "Keychain Access"
# Find certificate → Get Info → Trust → "Always Trust"
# On Linux, update certificates
sudo update-ca-certificates
# Project A
stoobly-agent ca-cert install --ca-certs-dir-path ~/project-a/.stoobly/ca_certs
# Project B
stoobly-agent ca-cert install --ca-certs-dir-path ~/project-b/.stoobly/ca_certs
# Use with specific project
stoobly-agent run --ca-certs-dir-path ~/project-a/.stoobly/ca_certs
# Create directory if missing
mkdir -p ~/.stoobly/ca_certs
# Try with sudo (Linux)
sudo stoobly-agent ca-cert install
# Check for errors
stoobly-agent ca-cert install --ca-certs-dir-path ~/.stoobly/ca_certs
# For Firefox:
# 1. Go to Settings → Privacy & Security → Certificates → View Certificates
# 2. Click "Import"
# 3. Select: ~/.mitmproxy/mitmproxy-ca-cert.pem
# 4. Trust for identifying websites
# Start proxy
stoobly-agent run --headless
# Configure browser proxy to localhost:8080
# Visit: https://example.com
# No certificate warning = CA cert is trusted
# Each team member runs:
stoobly-agent ca-cert install
# Now everyone can record/test HTTPS
# Share via git (optional - for custom CA)
git add .stoobly/ca_certs/
git commit -m "Add shared CA certificate"
# Team members install
git pull
stoobly-agent ca-cert install --ca-certs-dir-path ./.stoobly/ca_certs
# .gitignore (typical setup)
.stoobly/ca_certs/ # Don't commit
# OR for team sharing:
# Remove .stoobly/ca_certs/ from .gitignore
# Commit shared CA certificate
git add .stoobly/ca_certs/
git commit -m "Add shared CA certificate for team"
#!/bin/bash
# CI/CD script
# Install CA certificate
stoobly-agent ca-cert install --ca-certs-dir-path ./ci-ca-certs
# Run tests with HTTPS
stoobly-agent run --intercept --intercept-mode test &
AGENT_PID=$!
# Wait for agent to start
sleep 2
# Run test suite
npm test
# Cleanup
kill $AGENT_PID
# Dockerfile
FROM python:3.11
# Install stoobly-agent
RUN pip install stoobly-agent
# Copy CA certificate
COPY .stoobly/ca_certs /app/.stoobly/ca_certs
# Install CA certificate
RUN stoobly-agent ca-cert install --ca-certs-dir-path /app/.stoobly/ca_certs
# Run your application
CMD ["your-app"]
# Development only
stoobly-agent ca-cert install
# Production: Use proper SSL certificates from trusted CAs
# (Let's Encrypt, DigiCert, etc.)
# Remove old CA certificate
rm -rf ~/.mitmproxy/
rm -rf ~/.stoobly/ca_certs/
# Generate and install new one
stoobly-agent ca-cert install
# Regenerate host certificates
stoobly-agent ca-cert mkcert api.example.com
# Install CA certificate (required for HTTPS)
stoobly-agent ca-cert install
# Install to custom directory
stoobly-agent ca-cert install --ca-certs-dir-path /path/to/ca-certs
# Show certificate path
stoobly-agent ca-cert show --format pem
stoobly-agent ca-cert show --format cer
stoobly-agent ca-cert show --format p12
# Create certificate for hostname
stoobly-agent ca-cert mkcert api.example.com
# Create wildcard certificate
stoobly-agent ca-cert mkcert "*.example.com"
# Create certificate with custom paths
stoobly-agent ca-cert mkcert api.example.com \
--ca-certs-dir-path /path/to/ca-certs \
--certs-dir-path /path/to/output
# Uninstall CA certificate (coming soon)
stoobly-agent ca-cert uninstall
# Step 1: Install CA certificate
stoobly-agent ca-cert install
# Step 2: Create certificates for your domains (optional, auto-generated by proxy)
stoobly-agent ca-cert mkcert api.example.com
stoobly-agent ca-cert mkcert "*.myapp.local"
# Step 3: Start Stoobly proxy
stoobly-agent run --intercept --intercept-mode record
# Step 4: Configure your app to use proxy (localhost:8080)
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080
# Step 5: Make HTTPS requests (they get intercepted)
curl https://api.example.com/users
# Step 6: View recorded requests
stoobly-agent request list
# Install on macOS
stoobly-agent ca-cert install
# Open Keychain Access to verify
open -a "Keychain Access"
# Find "mitmproxy" certificate
# Double-click → Trust → "Always Trust"
# Close Keychain Access (it saves automatically)
# Restart browsers for changes to take effect
# Install on Linux
sudo stoobly-agent ca-cert install
# Update certificate store
sudo update-ca-certificates
# For Firefox, import manually
# Settings → Privacy & Security → Certificates → View Certificates → Import
# Select: ~/.mitmproxy/mitmproxy-ca-cert.pem
# Run Command Prompt as Administrator
# Right-click → "Run as administrator"
# Install CA certificate
stoobly-agent ca-cert install
# Certificate is added to Windows Certificate Store
# View: certmgr.msc → Trusted Root Certification Authorities
