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
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.
Claude Code — install from the shell:
claude plugin marketplace add semaphoreio/sem-ai
claude plugin install sem-ai@semaphoreio
The plugin drops every sem-ai skill (debug-pipeline, deploy, fix-flaky, gha-to-semaphore, init, manage-infra, probe-agent-environment, project-health, sem-ai-bootstrap, semaphore-blocks, semaphore-ci, semaphore-preflight, semaphore-promotions, semaphore-test-results, semaphore-toolbox, test-intelligence, testbox, watch-after-push) 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:
claude plugin marketplace update semaphoreio
claude plugin update sem-ai@semaphoreio # restart running sessions to apply
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:
Slash command
What it does
/sem-ai:init
Initialize Semaphore CI/CD for the current repo — detects state (GHA present → translate; greenfield → from scratch; .semaphore/ already → refine), applies defaults from the linked skills, validates, wires secrets, opens a PR
/sem-ai:gha-to-semaphore
Translate only — same procedure as init's translate path, scoped to converting .github/workflows/*
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.
Skills-only install (npx skills, any agent)
Prefer the full plugin above on Claude Code / Codex — it also wires the MCP server and the SessionStart hooks. For other agents (Cursor, OpenCode, …) or when you want just the skill instructions, use the cross-agent skills installer. It reads sem-ai's .claude-plugin/marketplace.json manifest, so it finds the bundle even though the skills live under assets/plugin/skills/:
npx skills add semaphoreio/sem-ai --list # list available skills
npx skills add semaphoreio/sem-ai --all # install all of them
npx skills add semaphoreio/sem-ai --skill semaphore-ci --skill watch-after-push
npx skills add semaphoreio/sem-ai --all -g # user-level (every repo)
npx skills add semaphoreio/sem-ai --all --agent cursor opencode
Two caveats:
Skills only.npx skills installs SKILL.md files — not the MCP server and not the SessionStart hooks (release-update check, Semaphore-repo awareness). For those, use the plugin install above.
The CLI is a prerequisite. Every skill shells out to sem-ai; install the binary first (see Install) and run sem-ai connect. npx skills installs instructions, not the CLI.
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.
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.
List pipelines (trimmed summaries, last 30 days by default; --full for the raw payload over the full history)
pipeline stop <id>
Stop a pipeline
pipeline rebuild <id>
Trigger partial rebuild (API call only)
pipeline promote <id>
Trigger a promotion (deploy)
pipeline topology <id>
Show block dependency graph
Jobs
Command
Description
job list --states RUNNING
List jobs by state
job show <id>
Show job details
job log <id>
Fetch structured job logs
job stop <id>
Stop a running job
Analytics
Command
Description
analytics summary --project <p>
Pass rate, duration, failures, deploys — all in one
analytics duration --project <p>
Duration trends (avg, p50, p95) with phase breakdown
analytics failures --project <p>
Block-level failure rates and failure reasons
analytics queue --project <p>
Queue wait time stats
analytics deploys --project <p>
Deploy frequency (per day / per week)
analytics trend --project <p>
Week-over-week trends for all key metrics
All analytics commands accept --project (auto-detected from git), --days, --branch, and --limit. analytics trend uses --weeks instead of --days.
Test intelligence
Command
Description
test summary --pipeline <id>
Parsed test results with file:line:message
test report --pipeline <id>
Detailed test report
test flaky --project <p>
Detect flaky tests across recent runs
Deployment targets
Command
Description
deploy targets --project <p>
List targets
deploy show <id>
Show target details
deploy history <id>
Deployment history
deploy create <name>
Create a target
deploy activate <id>
Activate a target
deploy deactivate <id>
Deactivate a target
deploy delete <id>
Delete a target
Pre-flight checks
Commands that run at pipeline initialization, before any block. One check per organization, one per project — --project selects the project check, omitting it selects the organization-wide one.
Command
Description
pfc show [--project <p>]
Show the check (commands, secrets, agent)
pfc apply [--project <p>]
Create or replace the check, from flags or --from-file
pfc delete [--project <p>]
Remove the check
Secrets
Command
Description
secret list
List secrets (org or project level)
secret show <name>
Show secret details
secret create <name>
Create a secret
secret update <name>
Update a secret
secret delete <name>
Delete a secret
Notifications, tasks, agents
Command
Description
notification list/show/create/delete
Notification rules
task list/show/create/update/run/delete
Scheduled tasks
agent types/show/list/delete
Self-hosted agent management
Artifacts
Command
Description
artifact list --scope jobs --id <id>
List artifacts
artifact get --scope jobs --id <id> --path <p>
Download an artifact
Utility
Command
Description
open
Open workflow/pipeline in browser
watch <workflow-id>
Poll workflow until done, streaming status
version
Print version information
yaml validate --file <path>
Validate pipeline YAML
troubleshoot workflow/pipeline/job <id>
Server-side diagnostics
Compound commands
These compose multiple API calls into a single operation.
Command
What it does
status
CI status for a branch — pipeline state, block results
diagnose
Full failure diagnosis — logs, test results, root cause
health
Project health — pass rates, trends, deploy status, verdict
analytics summary
All-in-one analytics overview for a project over a time window
Promote and block until promoted pipeline finishes
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
Pinning a context per invocation
context switch writes the shared active-context key in ~/.sem.yaml, so concurrent sessions (e.g. multiple agents on one machine) can flip each other's context mid-run. To pin a context without touching the file, pass --context on any command or set SEM_CONTEXT:
sem-ai --context myorg_semaphoreci_com project list # this invocation only
export SEM_CONTEXT=myorg_semaphoreci_com # every later call in this shell
Resolution precedence:
--context flag (named context, read-only)
SEM_CONTEXT env (named context, read-only)
SEMAPHORE_HOST / SEMAPHORE_API_TOKEN env (raw credentials, no config file needed)
active-context from ~/.sem.yaml
An explicit selector (1 or 2) fully shadows everything below it — no mixing of context credentials with env credentials. Without a selector, the raw env vars override the active context's values field by field.
An unknown context name fails hard and lists the available contexts — except on the commands that create or report that state. connect, signin, context switch, and context list ignore both selectors: a pin naming a context that does not exist yet must not stop the command about to create it, and context list/switch report what ~/.sem.yaml stores, so their active marking follows the file. context show reports what the current invocation resolves to, pin included, and each context list row carries pinned so a pinned caller can tell which one it is actually using.
The selector is ignored on those commands, not applied to them: connect names the context it creates after its host (dots become underscores), so SEM_CONTEXT=neworg sem-ai connect neworg.semaphoreci.com TOKEN creates neworg_semaphoreci_com and leaves the pin pointing at a name that still does not exist. Onboarding then means updating the pin to the created name. Where connect is given both a <host> and a selector that resolves to a different host, it refuses rather than picking one — it stores a token and moves active-context, so a two-organization invocation is a mistake worth failing.
signin ignores the selector too, and says so on stderr. A context names an organization; signin authenticates an account against a deployment, and on Semaphore Cloud every organization's account lives on me.semaphoreci.com with the CLI-auth endpoints on id.semaphoreci.com. Taking signin's host from a pinned organization context would post the device flow to a host that does not serve it. Pass [host] for another deployment.
Neither connect nor signin is exposed over MCP. signin runs a device flow that would hold the server's execution lock for the life of the grant and print its one-time code into a buffer the human only sees once the call returns; connect takes two positional arguments, which the tool-argument encoding cannot carry. Onboard on the command line, then point the MCP server at the context it created.
This pins the read path: no selector changes active-context or any stored credential. (Any invocation still creates an empty ~/.sem.yaml when none exists.) context switch, connect, and signin still write it, and active-context stays a shared key; pinning is how a session opts out of reading it.
Writes replace the file through a temp file plus rename(2) (which needs a writable directory, so a config file deliberately made read-only is replaced rather than refused, and comes back 0600), so a concurrent reader sees either the old config or the new one, never a half-written file. That is torn-read protection only: each write serializes the whole config as the writing process last read it, so two writes that overlap are last-writer-wins for the entire file — a context added by one can disappear when the other lands. Sequence commands that write, or let one session own the file. (The atomic path covers YAML; if viper picked up a non-YAML ~/.sem.json, that write is still in-place.)
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
Create cmd/<resource>.go
Define a cobra.Command with RunE, Short, Example
Register it in init() with rootCmd.AddCommand() or as a subcommand
The command automatically appears in discover, MCP tools, and --help
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Sem Ai?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Sem Ai precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.