semacli 0.5.10

A CLI tool to manage Semaphore UI (ansible-semaphore) via HTTP REST API

semacli

A CLI tool to manage Semaphore UI (ansible-semaphore) via its HTTP REST API.

Designed for LLM/agent and automation use — deterministic commands, JSON output, exit codes.

Features

• List projects, templates, inventories, environments
• Launch and monitor tasks
• Read task output
• JSON output support
• Bearer-token authentication (User Settings → API Tokens)

Installation

# From PyPI
pip install semacli

# From source
pip install git+https://github.com/lduchosal/semacli.git

# Development
git clone https://github.com/lduchosal/semacli.git
cd semacli
pdm install

Quick Start

Configuration

Create semacli.ini in the current directory or ~/.semacli.ini:

[semaphore]
url = https://monitor.example.com/semaphore
project = 1

[auth]
method = bearer_token
bearer_token = your-api-token-here

[settings]
timeout = 30
verify_ssl = true

Get a bearer token from the Semaphore UI: User Settings → API Tokens → Create.

Basic Usage

# Ping the API
sem ping

# List projects
sem projects

# (more commands wired in as the CLI grows)

Output Options

# JSON output
sem projects --json

# Verbose debugging
sem projects -v
sem projects -vv
sem projects -vvv

Configuration Options

Authentication Methods

Bearer token (recommended)

[semaphore]
url = https://monitor.example.com/semaphore

[auth]
method = bearer_token
bearer_token = your-api-token

Bearer token from environment variable

[semaphore]
url = https://monitor.example.com/semaphore

[auth]
method = env_var
env_var = SEMAPHORE_TOKEN

Shell hooks around sem run

Declare [hook] keys in semacli.ini to fire shell commands before/after a template run. Useful for syncing a remote repo, sending notifications, or paging on failure. Relative paths resolve against the .ini directory.

[hook]
# Aborts the run with exit 6 on non-zero. Receives env vars:
#   SEMACLI_TEMPLATE, SEMACLI_LIMIT, SEMACLI_TAGS, SEMACLI_PROJECT,
#   SEMACLI_TEMPLATE_ID, SEMACLI_CONFIG, SEMACLI_EVENT
task_run_prehook = scripts/sync-svn.sh

# Fires after watch completes (any status). Failures = warnings only.
# Also receives SEMACLI_TASK_ID and SEMACLI_STATUS.
task_run_posthook = scripts/notify.sh

# Same envelope as posthook, fires only when status != success.
task_run_failhook = scripts/page-oncall.sh

# Default 60s, applies per-hook.
timeout = 30

Pass --no-hooks on sem run to bypass them (debug / replay).

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Authentication error
4	API error
5	Not found
6	Hook aborted the command (pre-hook returned non-zero or timed out)

Development

# Clone and setup
git clone https://github.com/lduchosal/semacli.git
cd semacli
pdm install -G dev

# Run tests
pdm test

# Lint and format
pdm lint
pdm format

# Type check
pdm typecheck

# Build
pdm build

Architecture

semacli/
├── cli/                    # Click CLI interface
│   ├── commands/           # Individual commands
│   ├── decorators.py       # Common CLI options
│   └── handlers.py         # Error handlers
├── core/                   # Core business logic
│   ├── client.py           # Semaphore HTTP client
│   ├── config.py           # Configuration
│   ├── exceptions.py       # Custom exceptions
│   └── models.py           # Data models
└── services/               # Business services

See ARCHITECTURE.md for the wiki classification map used by ken wiki groom.

License

MIT License - see LICENSE for details.

Related Projects

• nagioscli - sibling CLI for Nagios Core (model project)