Scaffold

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 Docker-based 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-agent scaffold app create my-app

# Add a service
stoobly-agent scaffold service create api

Q: Why should I use scaffold for team development?

A: Scaffold provides version-controlled configuration, consistent environments across team members, Docker-based isolation, and automated workflow management for recording, mocking, and testing APIs.

Example:

# Team member 1 creates the scaffold
stoobly-agent scaffold app create team-project

# Team member 2 clones and uses it
git clone <repo>
make -f .stoobly/services/.Makefile record

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:

#!/bin/bash

# Create scaffold app that runs on docker
# This creates .stoobly/services/ in the current directory
stoobly-agent scaffold app create my-app \
--run-on docker

# 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

# Example: Start mock workflow
# stoobly-agent scaffold workflow up mock \
# --hostname-install-confirm y \
# --ca-certs-install-confirm y

# Example: Start test workflow
# stoobly-agent scaffold workflow up test \
# --hostname-install-confirm y \
# --ca-certs-install-confirm y

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.

Example:

stoobly-agent scaffold app create my-app
# Creates .stoobly/services/ structure in current directory

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:

# 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

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:

stoobly-agent scaffold app create my-app --proxy-port 9090 --ui-port 5000

Q: How do I create a scaffold app with test framework integrations?

A: Use the --plugin option to include Cypress or Playwright integrations.

Example:

# With Cypress
stoobly-agent scaffold app create my-app --plugin cypress

# With Playwright
stoobly-agent scaffold app create my-app --plugin playwright

# With both
stoobly-agent scaffold app create my-app --plugin cypress --plugin playwright

Q: What runtime environments are supported for scaffold apps?

A: Scaffold supports Docker (default) and local runtime environments.

Example:

# Docker-based (default)
stoobly-agent scaffold app create my-app --run-on docker

# Local runtime
stoobly-agent scaffold app create my-app --run-on local

# Both
stoobly-agent scaffold app create my-app --run-on docker --run-on local

Q: What files are created when I scaffold an app?

A: Scaffolding creates a .stoobly/services/ directory in the current directory with Docker configurations, Makefile, service definitions, and workflow templates.

Example:

stoobly-agent scaffold app create my-app
ls -la .stoobly/services/
# .Makefile, .Dockerfile.context, .docker-compose.base.yml, etc.

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:

# 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

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:

# From within the app directory
stoobly-agent scaffold service create api --hostname api.example.com

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:

# 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

Q: 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:

  • --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.

Examples:

# Example 1:
# 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 \
  --hostname api.local \
  --port 3000 \
  --scheme http \
  --local \
  --upstream-port 3001

# Example 2: 
# Main or client application (serves assets e.g. HTML, JS, Image files) 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. assets.local
# Specify a port e.g. 4200
# Run your frontend service on the same port
stoobly-agent scaffold service create assets \
  --hostname main.local \
  --port 4200 \
  --scheme http \
  --workflow test 

# Example 3: 
# Asset service (serves assets e.g. HTML, JS, Image files) running on http://localhost:8000
# DO NOT set --workflow record option, assets in most cases should not be recorded
# Specify a hostname, e.g. assets.local
# Specify a port e.g. 4200
# Run your frontend service on the same port
stoobly-agent scaffold service create assets \
  --hostname assets.local \
  --local \
  --port 8000 \
  --scheme http \
  --workflow mock \
  --workflow test

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:

# 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

# Local service - 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

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:

# 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

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:

stoobly-agent scaffold service create api \
  --env DATABASE_URL=postgres://localhost/db \
  --env API_KEY=secret123

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:

# 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

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:

stoobly-agent scaffold service create api
# Creates: record, mock, and test workflows automatically

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:

# 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/

Example init script:

#!/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

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:

# 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

Q: How do I view details about a specific service?

A: Use scaffold service show with the service name.

Example:

stoobly-agent scaffold service show api

Q: How do I list services in a specific format?

A: Use the --format option to specify output format (table, json, csv).

Example:

# JSON format
stoobly-agent scaffold service list --format json

# CSV format
stoobly-agent scaffold service list --format csv

Q: How do I filter services by workflow?

A: Use the --workflow option to filter services by their workflows.

Example:

# 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

Q: How do I update a service configuration?

A: Use scaffold service update with the options you want to change.

Example:

stoobly-agent scaffold service update api \
  --hostname api.newdomain.com \
  --port 9090

Q: How do I rename a service?

A: Use scaffold service update with the --name option.

Example:

stoobly-agent scaffold service update old-api --name new-api

Q: How do I delete a service?

A: Use scaffold service delete with the service name.

Example:

stoobly-agent scaffold service delete api

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:

# Start record workflow
stoobly-agent scaffold workflow up record

# Start mock workflow
stoobly-agent scaffold workflow up mock

# Start test workflow
stoobly-agent scaffold workflow up test

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:

# From within the app directory (default)
stoobly-agent scaffold workflow up record

# Or specify the app directory
stoobly-agent scaffold workflow up record --app-dir-path ./my-app

Q: How do I stop a workflow?

A: Use scaffold workflow down with the workflow name to stop all services.

Example:

stoobly-agent scaffold workflow down record

Q: How do I view logs from a workflow?

A: Use scaffold workflow logs to display logs from workflow services.

Example:

stoobly-agent scaffold workflow logs record

Q: How do I start a workflow with specific services only?

A: Use the --service option to select which services to run.

Example:

# Run only api and database services
stoobly-agent scaffold workflow up record --service api --service database

Q: How do I start a workflow in detached mode?

A: Use the --detached flag to run the workflow in the background.

Example:

stoobly-agent scaffold workflow up record --detached

Q: How do I skip hostname installation prompts?

A: Use the --hostname-install-confirm option to automatically confirm or deny hostname installation.

Example:

# Automatically confirm
stoobly-agent scaffold workflow up record --hostname-install-confirm y

# Automatically deny
stoobly-agent scaffold workflow up record --hostname-install-confirm n

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:

stoobly-agent scaffold workflow up record --ca-certs-install-confirm y

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:

# Create a custom workflow based on the record template
stoobly-agent scaffold workflow create staging \
  --template record \
  --service api

Q: What templates can I use for custom workflows?

A: You can use mock, record, or test as templates for custom workflows.

Example:

# Custom workflow based on mock template
stoobly-agent scaffold workflow create dev-mock --template mock --service api

# Custom workflow based on test template
stoobly-agent scaffold workflow create integration-test --template test --service api

Q: How do I create a custom workflow for multiple services?

A: Use multiple --service options to include multiple services in the workflow.

Example:

stoobly-agent scaffold workflow create full-stack \
  --template record \
  --service api \
  --service frontend \
  --service database

Q: How do I copy an existing workflow?

A: Use scaffold workflow copy to duplicate a workflow with a new name.

Example:

# Copy record workflow to staging workflow
stoobly-agent scaffold workflow copy record staging \
  --service api

SSL/TLS Certificate Management

Q: How do I generate SSL certificates for HTTPS services?

A: Use the --mkcert flag when starting a workflow or use scaffold app mkcert.

Example:

# Generate certs when starting workflow
stoobly-agent scaffold workflow up mock --mkcert

# Or generate certs separately
stoobly-agent scaffold app mkcert

Q: How do I generate certificates for specific services only?

A: Use the --service option with the mkcert command.

Example:

stoobly-agent scaffold app mkcert --service api --service frontend

Hostname Management

Q: How do I install hostnames for services?

A: Use scaffold hostname install to add service hostnames to /etc/hosts.

Example:

stoobly-agent scaffold hostname install --workflow record

Q: How do I uninstall hostnames for services?

A: Use scaffold hostname uninstall to remove service hostnames from /etc/hosts.

Example:

stoobly-agent scaffold hostname uninstall --workflow record

Q: How do I manage hostnames for specific services?

A: Use the --service option to target specific services.

Example:

stoobly-agent scaffold hostname install --workflow record --service api

Team Collaboration Workflows

Q: How do I set up a scaffold project for my team?

A: Create the scaffold app, add services, commit to version control, and team members can use the Makefile commands.

Example:

# Team lead setup
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
make -f .stoobly/services/.Makefile record

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:

# Record requests
make -f .stoobly/services/.Makefile record

# Create snapshot
make -f .stoobly/services/.Makefile scenario/snapshot key=abc123

# Commit and push
git add .stoobly/snapshots/
git commit -m "Add API request snapshots"
git push

Q: How do I run the same workflow across different environments?

A: Create custom workflows for each environment using templates.

Example:

# 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

Advanced Configuration

Q: How do I use a custom context directory?

A: Use the --context-dir-path option to specify a custom Stoobly data directory.

Example:

stoobly-agent scaffold workflow up record \
  --context-dir-path /path/to/custom/.stoobly

Q: How do I run workflows with custom namespaces?

A: Use the --namespace option to isolate workflow instances.

Example:

# Run record workflow with custom namespace
stoobly-agent scaffold workflow up record --namespace feature-branch

# Run another instance with different namespace
stoobly-agent scaffold workflow up record --namespace bug-fix

Q: How do I run workflows in dry-run mode?

A: Use the --dry-run flag to see what commands would be executed without running them.

Example:

stoobly-agent scaffold workflow up record --dry-run

Q: How do I increase logging verbosity?

A: Use the --log-level option to set the logging level.

Example:

stoobly-agent scaffold workflow up record --log-level debug

Q: How do I follow workflow logs in real-time?

A: Use the --follow flag with the logs command.

Example:

stoobly-agent scaffold workflow logs record --follow

CI/CD Integration

Q: How do I use scaffold in CI/CD pipelines?

A: Use non-interactive flags and environment variables to automate workflow execution.

Example:

#!/bin/bash
# CI/CD script
export STOOBLY_HOSTNAME_INSTALL_CONFIRM=y
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y

# Start test workflow
stoobly-agent scaffold workflow up test \
  --ca-certs-install-confirm y \
  --hostname-install-confirm y

# Run tests
npm test

# Clean up
stoobly-agent scaffold workflow down test

Q: How do I run workflows without publishing ports (for CI)?

A: Use the --no-publish flag to prevent port publishing.

Example:

stoobly-agent scaffold workflow up test --no-publish

Troubleshooting

Q: How do I validate my service configuration?

A: Use scaffold service show to view the current configuration.

Example:

stoobly-agent scaffold service show api

Q: What do I do if a workflow fails to start?

A: Check the logs for errors and verify service configurations.

Example:

# View logs
stoobly-agent scaffold workflow logs record

# Verify services
stoobly-agent scaffold service list

Q: How do I clean up all workflows?

A: Stop each workflow individually using the down command.

Example:

stoobly-agent scaffold workflow down record
stoobly-agent scaffold workflow down mock
stoobly-agent scaffold workflow down test

Quick Reference

Q: What's the typical workflow for setting up a team project?

A: Create app → Add services → Start workflow → Record/Mock/Test → Share with team.

Example:

# 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

# 4. Make requests (they get recorded)
curl http://api.local/users

# 5. Stop workflow
stoobly-agent scaffold workflow down record

# 6. Start mock workflow for testing
stoobly-agent scaffold workflow up mock

# 7. Run tests against mocks
npm test

# 8. Create snapshots and commit
make -f .stoobly/services/.Makefile scenario/snapshot key=abc123
git add .stoobly/
git commit -m "Add scaffold and snapshots"
git push
PreviousRunNextMakefile

Last updated

Was this helpful?