Stoobly Scaffold Commands - Questions & Answers for Team Use
Scaffold commands enable Stoobly for team collaboration. The workflow is: create an app, add services, and use the automatically generated record, mock, and test workflows for each service. Custom workflows can be created as needed.
Getting Started with Scaffold
Q: What is scaffolding in Stoobly?
A: Scaffolding creates a structured project setup for team collaboration, with workflows for recording, mocking, and testing HTTP requests across multiple services. The scaffold structure is created under .stoobly/services/ in the current directory.
Example:
# Create a scaffold app (creates .stoobly/services/ in current directory)stoobly-agentscaffoldappcreatemy-app# Add a servicestoobly-agentscaffoldservicecreateapi
Q: Why should I use scaffold for team development?
A: Scaffold provides version-controlled configuration, consistent environments across team members, and automated workflow management for recording, mocking, and testing APIs.
Example:
# Team member 1 creates the scaffoldstoobly-agentscaffoldappcreateteam-project# Team member 2 clones and uses itgitclone<repo>stoobly-agentscaffoldworkflowuptest
Q: How do I create a scaffold script for my project?
A: Create a shell script with only the scaffold creation commands (app and services). Include workflow commands as commented examples for reference. The contents of the script will depend on the type of services and workflows.
Example:
Creating an Application
Q: How do I create a new scaffold application?
A: Use scaffold app create with your application name to generate the scaffold structure under .stoobly/services/ in the current directory. By default, the app is created with local runtime (workflows run directly on your machine). To use Docker runtime instead, specify --runtime docker.
Example:
Q: How do I create a scaffold app in a specific directory?
A: By default, the scaffold is created in the current directory. Use the --app-dir-path option only when you need to specify a different location.
Example:
Q: How do I create a scaffold app with custom ports?
A: Use --proxy-port and --ui-port options to specify custom ports for the proxy and UI.
Example:
Q: How do I create a scaffold app with test framework integrations?
A: Use the --plugin option to include Cypress or Playwright integrations.
Example:
Q: What runtime environments are supported for scaffold apps?
A: Scaffold supports two runtime environments: local (default) and Docker. When you run scaffold app create without specifying --runtime, it defaults to local runtime, which runs workflows directly on your machine. Use --runtime docker to run workflows in Docker containers instead.
Example:
Q: How do I check whether my app is configured with local or Docker runtime?
A: Check the .stoobly/services/.config.yml file and look for the APP_RUNTIME configuration property to see which runtime is configured.
Example:
The APP_RUNTIME property will indicate whether the app is configured to run with local or Docker.
Q: What files are created when I scaffold an app?
A: Scaffolding creates a .stoobly/services/ directory in the current directory with service definitions and workflow templates.
Example:
Creating Services
Q: How do I add a service to my scaffold app?
A: Use scaffold service create with the service name to add a new service. By default, commands use the current directory. Use --app-dir-path only when you need to specify a different location.
Example:
Q: How do I create a service with a custom hostname?
A: Use the --hostname option to specify a custom hostname for the service.
Example:
Q: How do I create a service that proxies to a service that does not run on localhost?
A: Configure the service using --hostname, --port, and --scheme to define how clients connect to Stoobly. Only use --upstream-hostname, --upstream-port, and --upstream-scheme when the upstream server differs from these values.
Important:
The --upstream-* options are overrides, not replacements. Always set --hostname, --port, and --scheme first, then add --upstream-* options only when they differ. If the upstream uses the same port and scheme, do not specify --upstream-port or --upstream-scheme.
Example:
Q: How do I create a service for the application under test?
A: Create a service for your main application (the application being tested) using only the test workflow. Do not use --local, --workflow record, or --workflow mock options since the application under test should not be recorded or mocked.
Example:
Q: For Docker runtime, how do I create a service that proxies to a service that runs on localhost?
A: Use --hostname, --port, and --scheme to define how clients connect to Stoobly, then add the --local flag. You must specify --upstream-port with a different port than --port, and run your local service on that upstream port.
Important:
Docker runtime uses a reverse proxy (different from local runtime's foward proxy)
--port - The port Stoobly listens on (what clients/tests connect to)
--scheme - The scheme Stoobly uses (http or https)
--local - Automatically sets --upstream-hostname to localhost
--upstream-port - Required and must be different from --port - This is where your local service runs
--upstream-scheme - Optional - Only specify if your local service uses a different scheme than --scheme
Do not specify --upstream-hostname when using --local (it will be ignored)
You must run your local service on --upstream-port, not on --port
Different types of services have different recommended option configurations, match against the following examples.
Example:
Q: For local runtime, how do I create a service that proxies to a service that runs on localhost?
A: Set the hostname to localhost and do not use the --local option. Specify --port to match the port where your local service runs.
Important:
Local runtime uses a forward proxy (different from Docker runtime's reverse proxy)
--hostname - Must be localhost for local runtime
--port - The port where your local service runs (and where Stoobly will proxy)
--scheme - The scheme your service uses (http or https)
--local - Do not use this option with local runtime (it's only for Docker runtime)
Example:
Q: How do I set the port for a service?
A: Use the --port option to specify the port where Stoobly exposes the service (the port your tests/clients will use). For local services (using --local), you must specify --upstream-port with a different port and run your service on that upstream port.
Key difference:
--port - The port Stoobly listens on (what you connect to in tests) - always required
--upstream-port - The port of the actual service Stoobly proxies to - required when using --local and must be different from --port
Example:
Q: How do I control the startup order of services?
A: Use the --priority option (1.0-9.0) where lower values start first.
Example:
Q: How do I create a service with environment variables?
A: Use the --env option (can be used multiple times) to set environment variables.
Example:
Q: How do I create a service with specific workflows?
A: By default, all three workflows (mock, record, test) are created. Use the --workflow option only when you want to create a subset of workflows.
Common pattern: Frontend services that serve static assets typically only need the test workflow, as they don't require recording or mocking. The test workflow serves the built application from fixtures for E2E testing.
Example:
Q: What are the default workflows created for each service?
A: By default, three workflows are created: record (capture requests), mock (serve mocked responses), and test (validate responses).
Example:
Q: How do I set up a frontend service to serve static assets for E2E testing?
A: Frontend services typically only need the test workflow since they serve static assets from fixtures rather than recording or mocking requests. Modify the service's test/init script (located at .stoobly/services/<service-name>/test/init) to copy your built application to the public fixture folder.
Example:
Example init script:
This setup allows your E2E tests to request the application under test from the frontend service, which serves the static assets from the fixtures folder.
Managing Services
Q: How do I list all services in my scaffold app?
A: Use scaffold service list to display all configured services. Run from your app directory, or use --app-dir-path to specify the location.
Example:
Q: How do I view details about a specific service?
A: Use scaffold service show with the service name.
Example:
Q: How do I list services in a specific format?
A: Use the --format option to specify output format (table, json, csv).
Example:
Q: How do I filter services by workflow?
A: Use the --workflow option to filter services by their workflows.
Example:
Q: How do I update a service configuration?
A: Use scaffold service update with the options you want to change.
Example:
Q: How do I rename a service?
A: Use scaffold service update with the --name option.
Example:
Q: How do I delete a service?
A: Use scaffold service delete with the service name.
Example:
Working with Workflows
Q: What workflows are available by default?
A: Three workflows are created by default for each service: record (capture requests), mock (serve mocked responses), and test (validate responses).
Example:
Q: How do I start a workflow?
A: Use scaffold workflow up with the workflow name to start all services in that workflow. Run from your app directory, or use --app-dir-path to specify the location.
Example:
Q: How do I stop a workflow?
A: Use scaffold workflow down with the workflow name to stop all services.
⚠️ IMPORTANT: Always use stoobly-agent scaffold workflow down to stop workflows. DO NOT use Unix commands like pkill, kill, or docker stop - these can leave the system in an inconsistent state.
Example:
Q: How do I view logs from a workflow?
A: Use scaffold workflow logs to display logs from workflow services.
Example:
Q: How do I start a workflow with specific services only?
A: Use the --service option to select which services to run.
Example:
Q: How do I start a workflow in detached mode?
A: Use the --detached flag to run the workflow in the background.
Example:
Q: How do I skip hostname installation prompts?
A: Use the --hostname-install-confirm option to automatically confirm or deny hostname installation.
Example:
Q: How do I skip CA certificate installation prompts?
A: Use the --ca-certs-install-confirm option to automatically confirm or deny CA certificate installation.
Example:
Q: Which workflows support custom namespaces?
A: Namespaces are only supported by test workflows and custom workflows based on the test workflow template. Record and mock workflows do not support namespaces.
Supported:
test workflow
Custom workflows created with --template test
Not Supported:
record workflow
mock workflow
Custom workflows created with --template record or --template mock
Example:
Creating Custom Workflows
Q: How do I create a custom workflow?
A: Use scaffold workflow create with a workflow name and template to create a custom workflow.
Example:
Q: What templates can I use for custom workflows?
A: You can use mock, record, or test as templates for custom workflows.
Example:
Q: How do I create a custom workflow for multiple services?
A: Use multiple --service options to include multiple services in the workflow.
Example:
Q: How do I copy an existing workflow?
A: Use scaffold workflow copy to duplicate a workflow with a new name.
Example:
SSL/TLS Certificate Management
Q: How do I generate SSL certificates for HTTPS services?
A: Use scaffold app mkcert.
Example:
Q: How do I generate certificates for specific services only?
A: Use the --service option with the mkcert command.
Example:
Hostname Management
Q: How do I install hostnames for services?
A: Use scaffold hostname install to add service hostnames to /etc/hosts.
Example:
Q: How do I uninstall hostnames for services?
A: Use scaffold hostname uninstall to remove service hostnames from /etc/hosts.
Example:
Q: How do I manage hostnames for specific services?
A: Use the --service option to target specific services.
Example:
Team Collaboration Workflows
Q: How do I set up a scaffold project for my team?
A: Create the scaffold app, add services, and commit the configuration to version control so team members can use it.
Example:
Q: How do I share recorded requests with my team?
A: Use scenario snapshots to create committable files that can be shared via version control.
Example:
Q: How do I run the same workflow across different environments?
A: Create custom workflows for each environment using templates.
Example:
Quick Reference
Q: What's the complete end-to-end workflow for setting up and using a team project?
A: This is a comprehensive step-by-step guide covering the full workflow from initial setup through running tests and sharing results with your team.
#!/bin/bash
# This creates .stoobly/services/ in the current directory
# For E2E testing, include --plugin playwright or --plugin cypress
stoobly-agent scaffold app create my-app --plugin playwright
# Add API service (service runs on localhost:8080, exposed as api.local:80)
# Note: --port and --upstream-port must differ when using --local
# Run your API service on port 8080 (not 80)
stoobly-agent scaffold service create api \
--hostname api.local \
--port 80 \
--scheme http \
--local \
--upstream-port 8080
# Example: Start record workflow
# stoobly-agent scaffold workflow up record \
# --hostname-install-confirm y \
# --ca-certs-install-confirm y
#
# stoobly-agent scaffold intercept enable
# Example: Start mock workflow
# stoobly-agent scaffold workflow up mock
# Example: Start test workflow
# stoobly-agent scaffold workflow up test
# Creates app with local runtime (default)
stoobly-agent scaffold app create my-app
# Creates .stoobly/services/ structure in current directory
# Or explicitly specify local runtime
stoobly-agent scaffold app create my-app --runtime local
# Or use Docker runtime
stoobly-agent scaffold app create my-app --runtime docker
# Create in current directory (default)
stoobly-agent scaffold app create my-app
# Create in specific directory (optional)
stoobly-agent scaffold app create my-app --app-dir-path /path/to/projects
# From within the app directory (default)
stoobly-agent scaffold service create api
# Or specify the app directory
stoobly-agent scaffold service create api --app-dir-path ./my-app
# From within the app directory
stoobly-agent scaffold service create api --hostname api.example.com
# Example 1. When upstream differs from service (e.g., proxying production API locally)
# Clients connect to http://api.local:80 → Stoobly forwards to https://api.production.com:443
stoobly-agent scaffold service create api \
--hostname api.local \
--port 80 \
--scheme http \
--upstream-hostname api.production.com \
--upstream-port 443 \
--upstream-scheme https
# Example 2. When upstream matches service hostname and port (no --upstream-* needed)
# Clients connect to http://app.example.com:80 → Stoobly forwards to http://app.example.com:80
stoobly-agent scaffold service create ui \
--hostname app.example.com \
--port 80 \
--scheme http
# Application under test service is run locally for development but built when testing, running on http://localhost:4200
# DO NOT set --local option, this is the service used for development or testing
# DO NOT set --workflow record and --workflow mock options, main application should not have either
# Specify a hostname, e.g. main.local
# Specify a port e.g. 4200
# Run your frontend service on the same port
stoobly-agent scaffold service create main.local \
--hostname main.local \
--port 4200 \
--scheme http \
--workflow test
# Local API service running on http://localhost:3000
# Specify a hostname, e.g. api.local
# Specify a port e.g. 3000
# Run your API service on a different port from 3000, e.g. 3001
# Clients connect to http://api.local:3000 → Stoobly forwards to http://localhost:3001
stoobly-agent scaffold service create api.local \
--hostname api.local \
--port 3000 \
--scheme http \
--local \
--upstream-port 3001
# Local API service running on http://localhost:3000
# Hostname must be localhost for local runtime
# Port matches the port your service runs on
# Do NOT use --local option
stoobly-agent scaffold service create api \
--hostname localhost \
--port 3000 \
--scheme http
# Remote service where Stoobly port matches upstream port (no --upstream-port needed)
# Specify a hostname, e.g. api.local
# Specify a port, e.g. 8080
# Clients connect to http://api.local:8080 → Stoobly forwards to http://api.local:8080
stoobly-agent scaffold service create api \
--hostname api.local \
--port 8080 \
--scheme http
# Docker runtime local service (not applicable to local runtime) - ports must differ
# Local API service normally runs on http://localhost:3000
# Specify a hostname, e.g. api.local
# Specify a port e.g. 3000
# Run your API service on a different port from the specified one from 3000, e.g. 3001
# Clients connect to http://api.local:3000 → Stoobly forwards to http://localhost:3001
stoobly-agent scaffold service create api \
--hostname api.local \
--port 3000 \
--scheme http \
--local \
--upstream-port 3001
# Database starts first (priority 1)
stoobly-agent scaffold service create database --priority 1.0
# API starts second (priority 2)
stoobly-agent scaffold service create api --priority 2.0
# Frontend starts last (priority 3)
stoobly-agent scaffold service create frontend --priority 3.0
stoobly-agent scaffold service create api \
--env DATABASE_URL=postgres://localhost/db \
--env API_KEY=secret123
# All workflows (default - no --workflow needed)
stoobly-agent scaffold service create api
# Frontend service - only test workflow (serves static assets from fixtures)
stoobly-agent scaffold service create frontend \
--hostname app.local \
--workflow test
# Only mock and test workflows
stoobly-agent scaffold service create api --workflow mock --workflow test
# Only record workflow
stoobly-agent scaffold service create api --workflow record
stoobly-agent scaffold service create api
# Creates: record, mock, and test workflows automatically
# Create frontend service with only test workflow
stoobly-agent scaffold service create frontend \
--hostname app.local \
--workflow test
# Edit .stoobly/services/frontend/test/init to copy built assets
# Add this to the init script:
# cp -r $APP_DIR_PATH/dist/. .stoobly/fixtures/public/
#!/bin/bash
# .stoobly/services/frontend/test/init
# Copy built frontend assets to public fixtures folder
cp -r $APP_DIR_PATH/dist/dist/. .stoobly/fixtures/public/
# The frontend service will serve these static files during E2E tests
# From within the app directory (default)
stoobly-agent scaffold service list
# Or specify the app directory
stoobly-agent scaffold service list --app-dir-path ./my-app
stoobly-agent scaffold service show api
# JSON format
stoobly-agent scaffold service list --format json
# CSV format
stoobly-agent scaffold service list --format csv
# Show only services with record workflow
stoobly-agent scaffold service list --workflow record
# Show services with mock or test workflows
stoobly-agent scaffold service list --workflow mock --workflow test
stoobly-agent scaffold service update api \
--hostname api.newdomain.com \
--port 9090
stoobly-agent scaffold service update old-api --name new-api
stoobly-agent scaffold service delete api
# Start record workflow
stoobly-agent scaffold workflow up record
stoobly-agent intercept enable
# Start mock workflow
stoobly-agent scaffold workflow up mock
# Start test workflow
stoobly-agent scaffold workflow up test
# From within the app directory (default)
stoobly-agent scaffold workflow up test
# Or specify the app directory
stoobly-agent scaffold workflow up test
stoobly-agent scaffold workflow down record
stoobly-agent scaffold workflow logs record
# Run only api and database services
stoobly-agent scaffold workflow up test --service api --service database
stoobly-agent scaffold workflow up test --detached
# Automatically confirm
stoobly-agent scaffold workflow up record --hostname-install-confirm y
# Automatically deny
stoobly-agent scaffold workflow up record --hostname-install-confirm n
stoobly-agent scaffold workflow up record --ca-certs-install-confirm y
# Supported - test workflow with namespace
stoobly-agent scaffold workflow up test --namespace my-namespace
# Supported - custom workflow based on test workflow template
stoobly-agent scaffold workflow create my-test --template test --service api
stoobly-agent scaffold workflow up my-test --namespace my-namespace
# NOT Supported - record workflow (will cause errors)
stoobly-agent scaffold workflow up record --namespace my-namespace # Does NOT work
# NOT Supported - mock workflow (will cause errors)
stoobly-agent scaffold workflow up mock --namespace my-namespace # Does NOT work
# Create a custom workflow based on the record template
stoobly-agent scaffold workflow create staging \
--template record \
--service api
# Custom workflow based on mock template
stoobly-agent scaffold workflow create dev-mock --template mock --service api
# Custom workflow based on test workflow template
stoobly-agent scaffold workflow create integration-test --template test --service api
stoobly-agent scaffold workflow create full-stack \
--template record \
--service api \
--service frontend \
--service database
# Copy record workflow to staging workflow
stoobly-agent scaffold workflow copy record staging \
--service api
# Generate SSL certs for all services
stoobly-agent scaffold app mkcert
# Generate SSL certs for all services in a workflow
stoobly-agent scaffold app mkcert --workflow <WORKFLOW-NAME>
stoobly-agent scaffold app mkcert --service api --service frontend
stoobly-agent scaffold hostname install --workflow record
stoobly-agent scaffold hostname uninstall --workflow record
stoobly-agent scaffold hostname install --workflow record --service api
stoobly-agent scaffold app create team-project
stoobly-agent scaffold service create local-api \
--hostname api.local \
--local \
--port 3000 \
--scheme http \
--upstream-port 3001
stoobly-agent scaffold service create staging-api \
--hostname api.staging \
--port 443 \
--scheme https
stoobly-agent scaffold service create frontend \
--hostname frontend.local \
--port 4200 \
--scheme http \
--workflow test
# Commit to git
git add .stoobly/
git commit -m "Add Stoobly scaffold configuration"
git push
# Team members use it
git pull
stoobly-agent scaffold workflow up mock
# Record requests
stoobly-agent scaffold workflow up record
stoobly-agent intercept enable
# Create snapshot
stoobly-agent scenario snapshot <SCENARIO-KEY>
# Commit and push
git add .stoobly/snapshots/
git commit -m "Add API request snapshots"
git push
# Create staging workflow
stoobly-agent scaffold workflow create staging --template record --service api
# Create production workflow
stoobly-agent scaffold workflow create production --template record --service api
# Use them
stoobly-agent scaffold workflow up staging
stoobly-agent scaffold workflow up production
# 1. Create app
stoobly-agent scaffold app create team-project
# 2. Add services
stoobly-agent scaffold service create local-api \
--hostname api.local \
--local \
--port 3000 \
--scheme http \
--upstream-port 3001
stoobly-agent scaffold service create staging-api \
--hostname api.staging \
--port 443 \
--scheme https
stoobly-agent scaffold service create frontend \
--hostname frontend.local \
--port 4200 \
--scheme http \
--workflow test
# 3. Start record workflow
stoobly-agent scaffold workflow up record
stoobly-agent intercept enable
# 4. Make requests (they get recorded)
curl http://api.local/users
# 5. Stop workflow
stoobly-agent scaffold workflow down record
# 6. Start mock workflow
stoobly-agent scaffold workflow up mock
# 7. Run tests against mocks
npm test
# 8. Create snapshots and commit
stoobly-agent scenario snapshot <SCENARIO-KEY>
git add .stoobly/
git commit -m "Add scaffold and snapshots"
git push
# 9. Setup test workflow
# Update .stoobly/services/entrypoint/test/run to run test command e.g. `npm test`
# 10. Start test workflow
stoobly-agent scaffold workflow up test
