{"id":51202800,"url":"https://github.com/semaphoreio/sem-ai","last_synced_at":"2026-06-28T01:31:28.262Z","repository":{"id":357416163,"uuid":"1231886686","full_name":"semaphoreio/sem-ai","owner":"semaphoreio","description":"AI-first CLI for Semaphore CI/CD. 80+ tools, embedded MCP server, JSON output","archived":false,"fork":false,"pushed_at":"2026-06-16T08:55:10.000Z","size":464,"stargazers_count":8,"open_issues_count":4,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T09:13:27.408Z","etag":null,"topics":["ai-agents","cd","ci","cli","continuous-delivery","continuous-integration","devops","golang","mcp","semaphore","semaphoreci"],"latest_commit_sha":null,"homepage":"https://semaphore.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semaphoreio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T11:35:26.000Z","updated_at":"2026-06-16T08:55:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semaphoreio/sem-ai","commit_stats":null,"previous_names":["semaphoreio/sem-ai"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/semaphoreio/sem-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semaphoreio%2Fsem-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semaphoreio%2Fsem-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semaphoreio%2Fsem-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semaphoreio%2Fsem-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semaphoreio","download_url":"https://codeload.github.com/semaphoreio/sem-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semaphoreio%2Fsem-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34874557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cd","ci","cli","continuous-delivery","continuous-integration","devops","golang","mcp","semaphore","semaphoreci"],"created_at":"2026-06-28T01:31:27.488Z","updated_at":"2026-06-28T01:31:28.254Z","avatar_url":"https://github.com/semaphoreio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sem-ai\n\nAgent-first CLI for [Semaphore CI/CD](https://semaphore.io). 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.\n\n## Why sem-ai\n\n- **JSON by default** — every command returns structured JSON. Agents parse it directly, humans use `--format table`\n- **Self-discovery** — `sem-ai discover` returns a full capability map. Every command supports `--examples`\n- **MCP server** — `sem-ai mcp` exposes all commands as native tools for Claude Code, Cursor, VS Code, and any MCP client\n- **Compound commands** — `diagnose` composes workflow → pipeline → failed jobs → logs → parsed test results into a single call\n- **Compatible** — shares `~/.sem.yaml` with the [legacy Semaphore CLI](https://github.com/semaphoreci/cli). Same tokens, same contexts\n\n**Full reference**: [docs.semaphore.io/reference/sem-ai-cli](https://docs.semaphore.io/reference/sem-ai-cli)\n\n## Install\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | sh\n```\n\nInstalls 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).\n\nRe-run the same command to update to the newest release (or to confirm you're already on the latest).\n\nWant to inspect what runs first? `curl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | less` before piping to `sh`.\n\n### Advanced / manual install\n\nFor users who want to inspect-then-build, pin a specific commit, or work offline:\n\n```sh\ngit clone https://github.com/semaphoreio/sem-ai.git\ncd sem-ai\nmake install\n```\n\nRequires Go 1.25+.\n\n### Plugin install (Claude Code / Codex)\n\nsem-ai ships its skill bundle as a Claude Code / Codex plugin.\n\n**Claude Code** — from inside the host, install with two slash commands:\n\n```\n/plugin marketplace add semaphoreio/sem-ai\n/plugin install sem-ai@semaphoreio\n```\n\n**Codex CLI** — install from the shell:\n\n```sh\ncodex plugin marketplace add semaphoreio/sem-ai\ncodex plugin add sem-ai@semaphoreio\n```\n\nThe 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-promotions, semaphore-test-results, semaphore-toolbox, test-intelligence, testbox, watch-after-push) into your host.\n\nClaude 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:\n\n```\n/plugin marketplace update semaphoreio\n/reload-plugins\n```\n\n(Note: there is no `/plugin update \u003cplugin\u003e@\u003cmarketplace\u003e` command — refresh the marketplace and let auto-update apply, or `uninstall` + `install` for a forced re-install.)\n\nSkills follow the [Agent Skills](https://agentskills.io) standard and give agents context on when and how to use each sem-ai command without reading documentation.\n\n#### Slash-command entry points\n\nUser-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:\n\n| Slash command | What it does |\n|---|---|\n| `/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 |\n| `/sem-ai:gha-to-semaphore` | Translate only — same procedure as `init`'s translate path, scoped to converting `.github/workflows/*` |\n\nOther 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.\n\n### Skills-only install (`npx skills`, any agent)\n\nPrefer 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`](https://github.com/vercel-labs/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/`:\n\n```sh\nnpx skills add semaphoreio/sem-ai --list             # list available skills\nnpx skills add semaphoreio/sem-ai --all              # install all of them\nnpx skills add semaphoreio/sem-ai --skill semaphore-ci --skill watch-after-push\nnpx skills add semaphoreio/sem-ai --all -g           # user-level (every repo)\nnpx skills add semaphoreio/sem-ai --all --agent cursor opencode\n```\n\nTwo caveats:\n\n- **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.\n- **The CLI is a prerequisite.** Every skill shells out to `sem-ai`; install the binary first (see [Install](#install)) and run `sem-ai connect`. `npx skills` installs instructions, not the CLI.\n\n## Updates\n\nWhen 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:\n\n```\nsem-ai 0.4.1 is available (you have 0.3.0). Upgrade:\n  curl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | sh\n```\n\nTo check from a shell at any time:\n\n```shell\nsem-ai version --check\n```\n\nTo opt out (honored by both the plugin hook and manual CLI):\n\n```shell\nexport SEM_AI_NO_UPDATE_CHECK=1\n```\n\nUpgrade by re-running the install script — it fast-paths if you're already on latest:\n\n```shell\ncurl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | sh\n```\n\n## Quick start\n\n```shell\n# Connect to your org (get token at https://me.semaphoreci.com/account)\nsem-ai connect myorg.semaphoreci.com YOUR_API_TOKEN\n\n# Check CI status\nsem-ai status --project my-app --branch main\n\n# Diagnose a failure — one command, full root cause\nsem-ai diagnose --project my-app --branch main\n```\n\n## MCP server\n\nRun sem-ai as a persistent MCP server. Starts once, handles all tool calls through the in-memory command tree.\n\n```shell\nsem-ai mcp\n```\n\n### Claude Code\n\nAdd to `.mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"semaphore\": {\n      \"command\": \"sem-ai\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nAll commands become native MCP tools (`project_list`, `diagnose`, `status`, `blast-radius`, etc). Long-running commands (`watch`, `promote-and-wait`) are excluded to prevent blocking.\n\n## Commands\n\n### Projects\n\n| Command | Description |\n|---------|-------------|\n| `project list` | List all projects |\n| `project show \u003cname\u003e` | Show project details |\n| `project update \u003cname\u003e` | Update project settings |\n| `project delete \u003cname\u003e` | Delete a project |\n\n### Workflows\n\n| Command | Description |\n|---------|-------------|\n| `workflow list --project \u003cp\u003e` | List workflows |\n| `workflow show \u003cid\u003e` | Show workflow details |\n| `workflow run --project \u003cp\u003e` | Rerun the latest workflow |\n| `workflow rerun \u003cid\u003e` | Rerun a workflow |\n| `workflow stop \u003cid\u003e` | Stop a workflow |\n\n### Pipelines\n\n| Command | Description |\n|---------|-------------|\n| `pipeline show \u003cid\u003e` | Show pipeline with blocks and jobs |\n| `pipeline list --project \u003cp\u003e` | List pipelines |\n| `pipeline stop \u003cid\u003e` | Stop a pipeline |\n| `pipeline rebuild \u003cid\u003e` | Trigger partial rebuild (API call only) |\n| `pipeline promote \u003cid\u003e` | Trigger a promotion (deploy) |\n| `pipeline topology \u003cid\u003e` | Show block dependency graph |\n\n### Jobs\n\n| Command | Description |\n|---------|-------------|\n| `job list --states RUNNING` | List jobs by state |\n| `job show \u003cid\u003e` | Show job details |\n| `job log \u003cid\u003e` | Fetch structured job logs |\n| `job stop \u003cid\u003e` | Stop a running job |\n\n### Analytics\n\n| Command | Description |\n|---------|-------------|\n| `analytics summary --project \u003cp\u003e` | Pass rate, duration, failures, deploys — all in one |\n| `analytics duration --project \u003cp\u003e` | Duration trends (avg, p50, p95) with phase breakdown |\n| `analytics failures --project \u003cp\u003e` | Block-level failure rates and failure reasons |\n| `analytics queue --project \u003cp\u003e` | Queue wait time stats |\n| `analytics deploys --project \u003cp\u003e` | Deploy frequency (per day / per week) |\n| `analytics trend --project \u003cp\u003e` | Week-over-week trends for all key metrics |\n\nAll analytics commands accept `--project` (auto-detected from git), `--days`, `--branch`, and `--limit`. `analytics trend` uses `--weeks` instead of `--days`.\n\n### Test intelligence\n\n| Command | Description |\n|---------|-------------|\n| `test summary --pipeline \u003cid\u003e` | Parsed test results with file:line:message |\n| `test report --pipeline \u003cid\u003e` | Detailed test report |\n| `test flaky --project \u003cp\u003e` | Detect flaky tests across recent runs |\n\n### Deployment targets\n\n| Command | Description |\n|---------|-------------|\n| `deploy targets --project \u003cp\u003e` | List targets |\n| `deploy show \u003cid\u003e` | Show target details |\n| `deploy history \u003cid\u003e` | Deployment history |\n| `deploy create \u003cname\u003e` | Create a target |\n| `deploy activate \u003cid\u003e` | Activate a target |\n| `deploy deactivate \u003cid\u003e` | Deactivate a target |\n| `deploy delete \u003cid\u003e` | Delete a target |\n\n### Secrets\n\n| Command | Description |\n|---------|-------------|\n| `secret list` | List secrets (org or project level) |\n| `secret show \u003cname\u003e` | Show secret details |\n| `secret create \u003cname\u003e` | Create a secret |\n| `secret update \u003cname\u003e` | Update a secret |\n| `secret delete \u003cname\u003e` | Delete a secret |\n\n### Notifications, tasks, agents\n\n| Command | Description |\n|---------|-------------|\n| `notification list/show/create/delete` | Notification rules |\n| `task list/show/create/run/delete` | Scheduled tasks |\n| `agent types/show/list/delete` | Self-hosted agent management |\n\n### Artifacts\n\n| Command | Description |\n|---------|-------------|\n| `artifact list --scope jobs --id \u003cid\u003e` | List artifacts |\n| `artifact get --scope jobs --id \u003cid\u003e --path \u003cp\u003e` | Download an artifact |\n\n### Utility\n\n| Command | Description |\n|---------|-------------|\n| `open` | Open workflow/pipeline in browser |\n| `watch \u003cworkflow-id\u003e` | Poll workflow until done, streaming status |\n| `version` | Print version information |\n| `yaml validate --file \u003cpath\u003e` | Validate pipeline YAML |\n| `troubleshoot workflow/pipeline/job \u003cid\u003e` | Server-side diagnostics |\n\n## Compound commands\n\nThese compose multiple API calls into a single operation.\n\n| Command | What it does |\n|---------|-------------|\n| `status` | CI status for a branch — pipeline state, block results |\n| `diagnose` | Full failure diagnosis — logs, test results, root cause |\n| `health` | Project health — pass rates, trends, deploy status, verdict |\n| `analytics summary` | All-in-one analytics overview for a project over a time window |\n| `analytics trend` | Week-over-week trends — pass rate, duration, queue, failures |\n| `critical-path \u003cid\u003e` | Longest dependency chain (bottleneck) |\n| `blast-radius \u003cid\u003e` | Root failures vs cascading cancellations |\n| `rerun-failed \u003cid\u003e` | Partial rebuild of failed blocks only |\n| `promote-and-wait \u003cid\u003e` | Promote and block until promoted pipeline finishes |\n\n## Testbox\n\nRun commands in a real Semaphore CI environment before pushing. Creates a warm VM, syncs your local code, executes commands via SSH.\n\n```shell\n# Start a testbox\nsem-ai testbox warmup --project my-app\n\n# Run tests in real CI env\nsem-ai testbox run --id \u003cid\u003e \"go test ./...\"\n\n# Interactive SSH\nsem-ai testbox ssh --id \u003cid\u003e\n\n# Stop when done\nsem-ai testbox stop --id \u003cid\u003e\n```\n\n## Output\n\nAll commands output JSON by default:\n\n```shell\nsem-ai status --project my-app          # JSON\nsem-ai status --project my-app -f table # human-readable table\nsem-ai status --project my-app -f yaml  # YAML\n```\n\nErrors are structured JSON on stderr:\n\n```json\n{\"error\": true, \"code\": \"not_found\", \"message\": \"project not found\", \"status\": 404}\n```\n\n## Configuration\n\nsem-ai uses `~/.sem.yaml` — the same config file as the [legacy Semaphore CLI](https://github.com/semaphoreci/cli). If you already have `sem` configured, sem-ai works immediately.\n\n```shell\nsem-ai connect myorg.semaphoreci.com YOUR_TOKEN  # add/update context\nsem-ai context list                               # list all orgs\nsem-ai context show                               # show active org\n```\n\n## Development\n\n```shell\n# Build\nmake build\n\n# Install locally\nmake install\n\n# Run tests\nmake test\n\n# Format and vet\nmake fmt\nmake vet\n```\n\n### Project structure\n\n```\ncmd/           Command implementations (one file per resource)\npkg/client/    HTTP client with retry, pagination, versioned API support\npkg/config/    Configuration loading from ~/.sem.yaml\npkg/output/    JSON/table/YAML output engine\npkg/testparse/ Test result parsers (Go, pytest, rspec, minitest, jest, ExUnit, JUnit)\npkg/gitutil/   Git remote/branch detection\n.agents/       Agent skill definitions\n```\n\n### Adding a command\n\n1. Create `cmd/\u003cresource\u003e.go`\n2. Define a `cobra.Command` with `RunE`, `Short`, `Example`\n3. Register it in `init()` with `rootCmd.AddCommand()` or as a subcommand\n4. The command automatically appears in `discover`, MCP tools, and `--help`\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemaphoreio%2Fsem-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemaphoreio%2Fsem-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemaphoreio%2Fsem-ai/lists"}