semacli 0.4.0

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
semacli ping

# List projects
semacli projects

# (more commands wired in as the CLI grows)

Output Options

# JSON output
semacli projects --json

# Verbose debugging
semacli projects -v
semacli projects -vv
semacli 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

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Authentication error
4	API error
5	Not found

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)