xbp 10.15.0

XBP is a zero-config build pack that can also interact with proxies, kafka, sockets, synthetic monitors.
Documentation

XBP

XBP (XYLEX Build Pack) is a deployment and operations CLI for single-service and multi-service projects. It combines build/run workflows, PM2 process management, diagnostics, nginx helpers, secrets workflows, and project version synchronization in one tool.

Features

  • monitoring
  • docker
  • kubernetes [exp]
  • kafka [exp]
  • pm2 [wip]

current version: 10.15.0

TL;DR (30-Second Start)

# 1) Install

cargo install xbp


# 2) Check project/runtime state

xbp ports

xbp services


# 3) Run and inspect

xbp service build api

xbp service start api

xbp logs api


# 4) Keep versions aligned

xbp version

xbp version patch

Why XBP

  • One CLI for local service workflows and server-side operations.
  • Supports Rust, Node.js, Next.js, Python, Express, and mixed repos.
  • Handles PM2 lifecycle, logs, snapshots, and environment inspection.
  • Includes version reconciliation across common manifest files and git tags.
  • Adds operational helpers for ports, nginx, diagnostics, and secrets.

Feature Overview

  • Project and service orchestration: services, service, redeploy, setup.
  • Process/runtime control: list, start, stop, flush, snapshot, resurrect, env, logs, tail.
  • Network and infra helpers: ports, nginx, diag, curl.
  • Configuration and security: config, secrets.
  • Version workflows: version report, bump, explicit set, git-tag view.
  • Optional monitoring command family (feature-gated build).
  • Optional Kubernetes helper (feature-gated): xbp kubernetes ... for manifest generation, apply, and readiness checks. Build with --features kubernetes.
  • Optional Docker helper (feature-gated): xbp -l / xbp list shows docker ps snapshot when built with --features docker.

Installation

Option 1: Build From Source

git clone https://github.com/xylex-group/xbp.git

cd xbp

cargo build --release

./target/release/xbp --help

Option 2: Install From Cargo

cargo install xbp

Verify Installation

xbp --version

xbp --help

Quick Start

# Discover project/runtime state

xbp ports

xbp services


# Build or run a service from xbp config

xbp service build api

xbp service start api


# Deploy flow shortcut

xbp redeploy api


# PM2 snapshots for recovery

xbp snapshot

xbp resurrect


# Version report across manifests and tags

xbp version

Configuration

XBP resolves project config in this order:

  1. .xbp/xbp.yaml
  2. .xbp/xbp.yml
  3. .xbp/xbp.json
  4. xbp.yaml
  5. xbp.yml
  6. xbp.json

Both YAML and JSON are supported. If no explicit project version is set, default is 0.1.0.

Minimal YAML

project_name: my-app
version: 0.1.0
port: 3000
build_dir: /path/to/project

Multi-Service Example

project_name: my-stack
version: 0.1.0
port: 3000
build_dir: /srv/my-stack

services:
  - name: api
    target: rust
    branch: main
    port: 3000
    root_directory: apps/api
    url: https://api.example.com
    commands:
      install: cargo fetch
      build: cargo build --release
      start: ./target/release/api

  - name: web
    target: nextjs
    branch: main
    port: 3001
    root_directory: apps/web
    commands:
      install: pnpm install
      build: pnpm run build
      start: pnpm run start

Core Fields

  • project_name: logical project name.
  • version: semantic version string for project-level versioning.
  • port: primary project port.
  • build_dir: absolute path to project root.
  • services: optional service list.
  • environment: optional environment variables.

Service Fields

  • name: service identifier.
  • target: rust, nextjs, nodejs, python, or expressjs.
  • branch: deploy branch.
  • port: service port.
  • root_directory: optional service-specific working directory.
  • url: optional public URL.
  • healthcheck_path: optional health route.
  • commands: optional pre, install, build, start, dev commands.

Command Cookbook

Project and Service Commands

  • xbp services: list services from config.
  • xbp service build <name>: run service build command.
  • xbp service install <name>: run service install command.
  • xbp service start <name>: run service start command.
  • xbp service dev <name>: run service dev command.
  • xbp redeploy <name>: redeploy one service.

Runtime and Operations

  • xbp list: PM2 process list.
  • xbp logs [project]: view PM2 logs.
  • xbp logs --ssh-host <host> --ssh-username <user> --ssh-password <pw>: remote logs.
  • xbp ports: active listening ports.
  • xbp ports --kill --port 3000: kill process(es) on a port.
  • xbp ports --nginx: include nginx mapping view.
  • xbp ports --full: include reconciled XBP project port data.
  • xbp diag: run environment diagnostics.
  • xbp nginx list: list discovered nginx sites.
  • xbp nginx show <domain>: show nginx config.
  • xbp nginx update --domain <domain> --port <port>: update upstream port.
  • xbp curl <url-or-domain>: quick endpoint health/content check.

PM2 Shortcuts

  • xbp snapshot: save PM2 process snapshot.
  • xbp resurrect: restore PM2 state.
  • xbp stop <target>: stop one process or all.
  • xbp flush [target]: flush logs globally or for a process.
  • xbp monitor check: one-shot monitor check.
  • xbp monitor start: monitor daemon.
  • xbp env <pm2-name-or-id>: show PM2 env.

Config, Setup, and Secrets

  • xbp setup: guided local setup helpers.
  • xbp config: show/open global XBP config paths.
  • xbp config --project: show current project config.
  • xbp secrets list: list required/local env keys.
  • xbp secrets push --file .env.local: push secrets to provider.
  • xbp secrets pull --output .env.local: pull secrets from provider.
  • xbp secrets verify: validate required env key availability.

Versioning

  • xbp version: full version report (manifests + tags + registry when configured).
  • xbp version --git: show normalized git tag versions.
  • xbp version major: bump major in tracked files.
  • xbp version minor: bump minor in tracked files.
  • xbp version patch: bump patch in tracked files.
  • xbp version <x.y.z>: set tracked files to an explicit semver.
  • xbp version <package>=<x.y.z>: update package assignment versions in tracked TOML files.

Version Management Details

xbp version resolves versions from configured files, local/remote git tags, and configured package registries. It normalizes prefixed tags (v1.2.3) and plain semver (1.2.3) into one comparison space.

Package Assignment Updates In TOML

xbp version <package>=<x.y.z> updates both forms in tracked TOML files:

  • <package> = "x.y.z"
  • <package> = { version = "x.y.z", ... }

Example:

xbp version tokio=1.45.1

Default Tracked Version Files

  • README.md
  • openapi.yaml
  • openapi.yml
  • Cargo.toml
  • Cargo.lock
  • package.json
  • package-lock.json
  • pyproject.toml
  • xbp.yaml
  • xbp.json
  • .xbp/xbp.yaml
  • .xbp/xbp.json

The registry is synchronized into global XBP config as versioning-files.yaml. Missing defaults are re-added without removing custom entries.

PM2 Behavior

XBP uses PM2 as an execution/runtime layer for many commands.

  • Deploy and start flows can (re)start services under PM2.
  • snapshot stores recoverable process state.
  • resurrect first tries native PM2 restore, then falls back to latest XBP snapshot.
  • env maps PM2 names to IDs and prints effective runtime environment.

Ports and Diagnostics

  • xbp ports reconciles active listeners with detected project and nginx metadata.
  • xbp diag validates common system dependencies and service expectations.

MCP Server

XBP includes an MCP stdio server at scripts/xbp_mcp_server.py. It exposes tools for all current xbp commands and includes xbp_raw for raw arg passthrough.

Run MCP Server

python3 scripts/xbp_mcp_server.py

What It Returns

Each tool call returns:

  • Executed command array.
  • Working directory.
  • Exit code.
  • Captured stdout/stderr.

Server Tests

python3 -m unittest scripts/test_xbp_mcp_server.py

Repository Layout

  • src/main.rs: binary entrypoint.
  • src/lib.rs: library exports.
  • src/cli/: clap command definitions and dispatch.
  • src/commands/: command implementations.
  • src/strategies/: deployment strategy and project detection.
  • src/sdk/: PM2 and nginx integrations.
  • src/utils/: shared helpers.
  • scripts/: support scripts including MCP server.

Development

cargo fmt

cargo test

python3 -m unittest scripts/test_xbp_mcp_server.py

Troubleshooting

  • If xbp is not found, ensure Cargo bin path is on PATH.
  • If PM2 commands fail, verify PM2 is installed and reachable in your shell env.
  • If nginx commands fail, run with elevated permissions where required.
  • If xbp version cannot update package assignments, confirm the target file is TOML and listed in versioning registry.
  • If MCP command calls fail, confirm xbp is installed on the same environment where xbp_mcp_server.py is running.

License

MIT