Manage application workflows including configuration, restart, and removal.
A workflow binds a shell command (e.g., npm run dev, python run.py, cargo run) to a long-running task managed by Replit. Workflows are used to run webservers, background services, TUIs, and other persistent processes.
Key characteristics:
Keep workflows minimal: One workflow per project is usually sufficient. Use the main frontend server or TUI as your primary workflow.
Choose the right workflow: If your project has a frontend or TUI, set the workflow to the process that updates what the user sees.
Clean up unused workflows: When adding new workflows, remove any existing workflows that are no longer needed.
Always restart after changes: Restart workflows after making server-side code changes to ensure updates are visible to the user. Verify they run without errors before returning to the user.
Use bash for one-off commands: Workflows are for persistent processes. Use bash for build scripts, testing, or commands that don't need to keep running.
Use this skill when:
List all configured workflows with their current state.
Parameters: None
Returns: List of workflow info dicts with name (str), command (str), and state ("not_started", "running", "finished", "failed").
Example:
const workflows = await listWorkflows();
for (const w of workflows) {
console.log(`${w.name}: ${w.state}`);
}
Get detailed status of a specific workflow including output logs and open ports.
Parameters:
name (str, required): Name of the workflow to checkmaxScrollbackLines (int, default 100): Number of output lines to includeReturns: Dict with name, command, state, output (recent terminal output), openPorts (list of listening ports), and waitForPort.
Example:
// Check if the server is running and see its output
const status = await getWorkflowStatus({ name: "Start application" });
console.log(`State: ${status.state}`);
if (status.output) {
console.log(`Output:\n${status.output}`);
}
if (status.openPorts) {
console.log(`Listening on ports: ${status.openPorts}`);
}
Configure or create a workflow. This is the primary way to set up background processes.
Parameters:
name (str, default "Start application"): Unique workflow identifiercommand (str, required): Shell command to executewaitForPort (int, optional): Port the process listens onoutputType (str, default "webview"): "webview", "console", or "vnc"autoStart (bool, default True): Auto-start after configurationisCanvasWorkflow (bool, default false): Whether this workflow serves canvas iframe contentOutput Type Rules:
Supported Ports: 3000, 3001, 3002, 3003, 4200, 5000, 5173, 6000, 6800, 8000, 8008, 8080, 8099, 9000
Examples:
// Web application (React, Next.js, etc.)
await configureWorkflow({
name: "Start application",
command: "npm run dev",
waitForPort: 3000,
outputType: "webview"
});
// Backend API
await configureWorkflow({
name: "Backend API",
command: "python api.py",
waitForPort: 8000,
outputType: "console"
});
// Desktop application
await configureWorkflow({
name: "Desktop App",
command: "python gui_app.py",
outputType: "vnc"
});
Remove a workflow by name. Automatically stops it if running.
Parameters:
name (str, required): Name of the workflow to removeReturns: Dict with success, message, workflowName, and wasRunning
Example:
await removeWorkflow({ name: "Backend API" });
Restart a workflow by name.
Parameters:
workflowName (str, required): Name of the workflow (e.g., "Start application")timeout (int, default 30): Timeout in seconds to wait for restartReturns: Dict with restart status and optional screenshot URL
Example:
// Restart the main application
const result = await restartWorkflow({ workflowName: "Start application" });
console.log(result.message);
// Restart with custom timeout
const result2 = await restartWorkflow({
workflowName: "Start application",
timeout: 60
});
Restart after code changes: Always restart workflows after modifying server-side code
Use appropriate timeouts: Increase timeout for applications with slow startup
Check logs on failure: If restart fails, check workflow logs for error details
One restart at a time: Avoid parallel restarts of the same workflow
Match port to your app: Use the port your application actually listens on
Start application - Main application workflowStart Backend - Backend server (in Expo/mobile apps)Project - Parent workflow for multi-service appsThe workflow functions may raise errors in these cases:
When errors occur, check:
// Create a web application workflow
await configureWorkflow({
name: "Start application",
command: "npm run dev",
waitForPort: 3000,
outputType: "webview"
});
// After making code changes, restart the application
const result = await restartWorkflow({ workflowName: "Start application" });
if (result.success) {
console.log("Application restarted successfully");
if (result.screenshotUrl) {
console.log(`Screenshot: ${result.screenshotUrl}`);
}
} else {
console.log(`Restart failed: ${result.message}`);
}
// Clean up unused workflows
await removeWorkflow({ name: "Old Backend" });