sem-ai

Agent-first CLI for Semaphore CI/CD. Structured JSON output, self-discovery, composable commands, and an embedded MCP server — built for AI agents to drive the full CI/CD loop without a browser.

Why sem-ai

• JSON by default — every command returns structured JSON. Agents parse it directly, humans use --format table
• Self-discovery — sem-ai discover returns a full capability map. Every command supports --examples
• MCP server — sem-ai mcp exposes all commands as native tools for Claude Code, Cursor, VS Code, and any MCP client
• Compound commands — diagnose composes workflow → pipeline → failed jobs → logs → parsed test results into a single call
• Compatible — shares ~/.sem.yaml with the legacy Semaphore CLI. Same tokens, same contexts

Full reference: docs.semaphore.io/reference/sem-ai-cli

Install

curl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | sh

Installs the latest release automatically. Supports macOS and Linux on amd64 and arm64. The binary is placed at $HOME/.local/bin/sem-ai when that directory is on $PATH, or at $HOME/.semaphore-ai/bin/sem-ai otherwise (a $PATH hint is printed to stderr in that case).

Re-run the same command to update to the newest release (or to confirm you're already on the latest).

Want to inspect what runs first? curl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | less before piping to sh.

Advanced / manual install

For users who want to inspect-then-build, pin a specific commit, or work offline:

git clone https://github.com/semaphoreio/sem-ai.git
cd sem-ai
make install

Requires Go 1.25+.

Plugin install (Claude Code / Codex)

sem-ai ships its skill bundle as a Claude Code / Codex plugin. From inside your AI host, install with two slash commands:

/plugin marketplace add semaphoreio/sem-ai
/plugin install sem-ai@semaphoreio

The plugin drops every sem-ai skill (debug-pipeline, deploy, gha-to-semaphore, init, manage-infra, probe-agent-environment, project-health, sem-ai-bootstrap, semaphore-blocks, semaphore-ci, semaphore-promotions, semaphore-test-results, semaphore-toolbox, test-intelligence, testbox) into your host.

Claude Code refreshes registered marketplaces at session start, picks up the new plugin version, and applies it automatically — there is no manifest flag to set for this. To force an immediate refresh:

/plugin marketplace update semaphoreio
/reload-plugins

(Note: there is no /plugin update <plugin>@<marketplace> command — refresh the marketplace and let auto-update apply, or uninstall + install for a forced re-install.)

Skills follow the Agent Skills standard and give agents context on when and how to use each sem-ai command without reading documentation.

Slash-command entry points

User-invocable skills can be triggered directly with a namespaced slash command — useful when the activation keyword in a skill's description doesn't match your intent verbatim:

Other skills are loaded automatically when their description keywords match the user's prompt; the slash commands above are explicit triggers for the most common entry points.

Updates

When running the sem-ai plugin in Claude Code or Codex, a SessionStart hook checks GitHub for new releases at most once every 6 hours and surfaces a one-line notice in chat when one is available:

sem-ai 0.4.1 is available (you have 0.3.0). Upgrade:
  curl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | sh

To check from a shell at any time:

sem-ai version --check

To opt out (honored by both the plugin hook and manual CLI):

export SEM_AI_NO_UPDATE_CHECK=1

Upgrade by re-running the install script — it fast-paths if you're already on latest:

curl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | sh

Quick start

# Connect to your org (get token at https://me.semaphoreci.com/account)
sem-ai connect myorg.semaphoreci.com YOUR_API_TOKEN

# Check CI status
sem-ai status --project my-app --branch main

# Diagnose a failure — one command, full root cause
sem-ai diagnose --project my-app --branch main

MCP server

Run sem-ai as a persistent MCP server. Starts once, handles all tool calls through the in-memory command tree.

sem-ai mcp

Claude Code

Add to .mcp.json in your project:

{
  "mcpServers": {
    "semaphore": {
      "command": "sem-ai",
      "args": ["mcp"]
    }
  }
}

All commands become native MCP tools (project_list, diagnose, status, blast-radius, etc). Long-running commands (watch, promote-and-wait) are excluded to prevent blocking.

Commands

Projects

Workflows

Pipelines

Jobs

Analytics

All analytics commands accept --project (auto-detected from git), --days, --branch, and --limit. analytics trend uses --weeks instead of --days.

Test intelligence

Deployment targets

Secrets

Notifications, tasks, agents

Artifacts

Utility

Compound commands

These compose multiple API calls into a single operation.

Testbox

Run commands in a real Semaphore CI environment before pushing. Creates a warm VM, syncs your local code, executes commands via SSH.

# Start a testbox
sem-ai testbox warmup --project my-app

# Run tests in real CI env
sem-ai testbox run --id <id> "go test ./..."

# Interactive SSH
sem-ai testbox ssh --id <id>

# Stop when done
sem-ai testbox stop --id <id>

Output

All commands output JSON by default:

sem-ai status --project my-app          # JSON
sem-ai status --project my-app -f table # human-readable table
sem-ai status --project my-app -f yaml  # YAML

Errors are structured JSON on stderr:

{"error": true, "code": "not_found", "message": "project not found", "status": 404}

Configuration

sem-ai uses ~/.sem.yaml — the same config file as the legacy Semaphore CLI. If you already have sem configured, sem-ai works immediately.

sem-ai connect myorg.semaphoreci.com YOUR_TOKEN  # add/update context
sem-ai context list                               # list all orgs
sem-ai context show                               # show active org

Development

# Build
make build

# Install locally
make install

# Run tests
make test

# Format and vet
make fmt
make vet

Project structure

cmd/           Command implementations (one file per resource)
pkg/client/    HTTP client with retry, pagination, versioned API support
pkg/config/    Configuration loading from ~/.sem.yaml
pkg/output/    JSON/table/YAML output engine
pkg/testparse/ Test result parsers (Go, pytest, rspec, minitest, jest, ExUnit, JUnit)
pkg/gitutil/   Git remote/branch detection
.agents/       Agent skill definitions

Adding a command

1. Create cmd/<resource>.go
2. Define a cobra.Command with RunE, Short, Example
3. Register it in init() with rootCmd.AddCommand() or as a subcommand
4. The command automatically appears in discover, MCP tools, and --help