list-deployments
Retrieve deployment history for a Railway service, showing IDs, statuses, and metadata to monitor application updates and track changes.
Instructions
List deployments for a Railway service with IDs, statuses and other metadata. Requires Railway CLI v4.10.0+.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspacePath | Yes | The path to the workspace to list deployments from | |
| service | No | Service name or ID to list deployments for (defaults to linked service) | |
| environment | No | Environment to list deployments from (defaults to linked environment) | |
| limit | No | Maximum number of deployments to show (default: 20, max: 1000) | |
| json | No | Return deployments as structured JSON data. When true, the output will contain ids, statuses, and other metadata |
Implementation Reference
- src/tools/list-deployments.ts:44-66 (handler)The tool's handler function. It calls the listDeployments helper with provided options, handles success/error responses, and returns formatted tool output using createToolResponse.handler: async (options: ListDeploymentsOptions) => { try { const result = await listDeployments(options); if (!result.success) { throw new Error(result.error); } return createToolResponse(result.output); } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return createToolResponse( "❌ Failed to list Railway deployments\n\n" + `**Error:** ${errorMessage}\n\n` + "**Next Steps:**\n" + "• Ensure you are logged into Railway CLI (`railway login`)\n" + "• Check that you have a project linked (`railway link`)\n" + "• Verify you have permissions to view deployments\n" + "• Try running `railway login` to refresh your authentication" ); } },
- src/tools/list-deployments.ts:11-43 (schema)Zod input schema defining validation and descriptions for tool parameters: workspacePath, service, environment, limit, json.inputSchema: { workspacePath: z .string() .describe("The path to the workspace to list deployments from"), service: z .string() .optional() .describe( "Service name or ID to list deployments for (defaults to linked service)" ), environment: z .string() .optional() .describe( "Environment to list deployments from (defaults to linked environment)" ), limit: z .number() .min(1) .max(1000) .default(20) .optional() .describe( "Maximum number of deployments to show (default: 20, max: 1000)" ), json: z .boolean() .default(false) .optional() .describe( "Return deployments as structured JSON data. When true, the output will contain ids, statuses, and other metadata" ), },
- src/index.ts:21-31 (registration)Dynamic registration loop that registers all exported tools (including 'list-deployments') with the MCP server using name, metadata (title, description, inputSchema), and handler.Object.values(tools).forEach((tool) => { server.registerTool( tool.name, { title: tool.title, description: tool.description, inputSchema: tool.inputSchema, }, tool.handler, ); });
- src/cli/deployment.ts:97-158 (helper)Supporting helper function that constructs and executes the 'railway deployment list' CLI command with input options, checks CLI version support, handles project linking and errors, returning success/output or error.export const listDeployments = async ({ workspacePath, service, environment, limit = 20, json = false, }: ListDeploymentsOptions): Promise< | { success: true; output: string; } | { success: false; error: string; } > => { try { await checkRailwayCliStatus(); const featureSupport = await getCliFeatureSupport(); if (!featureSupport.deployment.list) { const version = await getRailwayVersion(); return { success: false, error: `Railway CLI version ${ version || "unknown" } does not support 'deployment list' command. Please upgrade to version 4.10.0 or later.`, }; } const projectResult = await getLinkedProjectInfo({ workspacePath }); if (!projectResult.success) { return { success: false, error: projectResult.error ?? "Failed to get project info", }; } let command = "railway deployment list"; if (service) { command += ` --service ${service}`; } if (environment) { command += ` --environment ${environment}`; } if (limit) { command += ` --limit ${limit}`; } if (json) { command += " --json"; } const { output } = await runRailwayCommand(command, workspacePath); return { success: true, output }; } catch (error: unknown) { return analyzeRailwayError(error, `railway deployment list`); } };