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.

Example:

# Create a scaffold app
stoobly-agent scaffold app create my-app

# Add a service
stoobly-agent scaffold service create api --app-dir-path ./my-app

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>
cd team-project
make -f .stoobly/services/.Makefile record

---

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.

Example:

stoobly-agent scaffold app create my-app

Q: How do I create a scaffold app in a specific directory?

A: Use the --app-dir-path option to specify where to create the scaffold.

Example:

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 with Docker configurations, Makefile, service definitions, and workflow templates.

Example:

stoobly-agent scaffold app create my-app
ls -la my-app/.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.

Example:

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:

stoobly-agent scaffold service create api --hostname api.example.com --app-dir-path ./my-app

Q: How do I create a service that proxies to an upstream server?

A: Use --upstream-hostname and --upstream-port to configure the upstream service.

Example:

stoobly-agent scaffold service create api \
  --hostname api.local \
  --upstream-hostname api.production.com \
  --upstream-port 443 \
  --upstream-scheme https \
  --app-dir-path ./my-app

Q: How do I create a service for a local upstream server?

A: Use the --local flag to indicate the upstream service is running locally.

Example:

stoobly-agent scaffold service create frontend \
  --hostname frontend.local \
  --local \
  --upstream-port 3000 \
  --app-dir-path ./my-app

Q: How do I set the port for a service?

A: Use the --port option to specify the service port.

Example:

stoobly-agent scaffold service create api --port 8080 --app-dir-path ./my-app

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 --app-dir-path ./my-app

# API starts second (priority 2)
stoobly-agent scaffold service create api --priority 2.0 --app-dir-path ./my-app

# Frontend starts last (priority 3)
stoobly-agent scaffold service create frontend --priority 3.0 --app-dir-path ./my-app

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 \
  --app-dir-path ./my-app

Q: How do I create a service with specific workflows?

A: Use the --workflow option to specify which workflows to create (mock, record, test).

Example:

# Only mock and test workflows
stoobly-agent scaffold service create api --workflow mock --workflow test --app-dir-path ./my-app

# All workflows (default)
stoobly-agent scaffold service create api --workflow mock --workflow record --workflow test --app-dir-path ./my-app

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 --app-dir-path ./my-app
# Creates: record, mock, and test workflows automatically

---

Managing Services

Q: How do I list all services in my scaffold app?

A: Use scaffold service list to display all configured services.

Example:

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

# CSV format
stoobly-agent scaffold service list --format csv --app-dir-path ./my-app

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 --app-dir-path ./my-app

# Show services with mock or test workflows
stoobly-agent scaffold service list --workflow mock --workflow test --app-dir-path ./my-app

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 \
  --app-dir-path ./my-app

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 --app-dir-path ./my-app

Q: How do I delete a service?

A: Use scaffold service delete with the service name.

Example:

stoobly-agent scaffold service delete api --app-dir-path ./my-app

---

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 --app-dir-path ./my-app

# Start mock workflow
stoobly-agent scaffold workflow up mock --app-dir-path ./my-app

# Start test workflow
stoobly-agent scaffold workflow up test --app-dir-path ./my-app

Q: How do I start a workflow?

A: Use scaffold workflow up with the workflow name to start all services in that workflow.

Example:

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

# Automatically deny
stoobly-agent scaffold workflow up record --hostname-install-confirm n --app-dir-path ./my-app

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 --app-dir-path ./my-app

---

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 \
  --app-dir-path ./my-app

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 --app-dir-path ./my-app

# Custom workflow based on test template
stoobly-agent scaffold workflow create integration-test --template test --service api --app-dir-path ./my-app

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 \
  --app-dir-path ./my-app

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 \
  --app-dir-path ./my-app

---

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 --app-dir-path ./my-app

# Or generate certs separately
stoobly-agent scaffold app mkcert --app-dir-path ./my-app

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 --app-dir-path ./my-app

---

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

---

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 api --hostname api.local --upstream-hostname api.prod.com
stoobly-agent scaffold service create frontend --hostname frontend.local --local --upstream-port 3000

# Commit to git
git add .stoobly/
git commit -m "Add Stoobly scaffold configuration"
git push

# Team members use it
git pull
cd team-project
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 --app-dir-path ./my-app

# Create production workflow
stoobly-agent scaffold workflow create production --template record --service api --app-dir-path ./my-app

# Use them
stoobly-agent scaffold workflow up staging --app-dir-path ./my-app
stoobly-agent scaffold workflow up production --app-dir-path ./my-app

---

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 \
  --app-dir-path ./my-app

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 --app-dir-path ./my-app

# Run another instance with different namespace
stoobly-agent scaffold workflow up record --namespace bug-fix --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

---

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 \
  --app-dir-path ./my-app

# Run tests
npm test

# Clean up
stoobly-agent scaffold workflow down test --app-dir-path ./my-app

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 --app-dir-path ./my-app

---

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

# Verify services
stoobly-agent scaffold service list --app-dir-path ./my-app

Q: How do I clean up all workflows?

A: Stop each workflow individually using the down command.

Example:

stoobly-agent scaffold workflow down record --app-dir-path ./my-app
stoobly-agent scaffold workflow down mock --app-dir-path ./my-app
stoobly-agent scaffold workflow down test --app-dir-path ./my-app

---

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 api --hostname api.local --upstream-hostname api.prod.com --app-dir-path ./team-project
stoobly-agent scaffold service create frontend --hostname frontend.local --local --upstream-port 3000 --app-dir-path ./team-project

# 3. Start record workflow
stoobly-agent scaffold workflow up record --app-dir-path ./team-project

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

# 5. Stop workflow
stoobly-agent scaffold workflow down record --app-dir-path ./team-project

# 6. Start mock workflow for testing
stoobly-agent scaffold workflow up mock --app-dir-path ./team-project

# 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

This comprehensive guide covers all aspects of using Stoobly scaffold commands for team collaboration, from initial setup through advanced workflows and CI/CD integration.