apicentric-0.1.1 has been yanked.

Apicentric

A powerful CLI tool and API simulator platform for developers who love the terminal

What is Apicentric?

Apicentric is a Rust-based CLI tool and API simulator platform that helps developers:

🎯 Mock APIs with simple YAML configuration
✅ Test API contracts between services
🔄 Generate code (TypeScript types, React Query hooks)
🖥️ TUI (Terminal User Interface) for visual service management
🌐 P2P collaboration on service definitions (optional)

Perfect for frontend developers who need backend APIs, teams doing contract testing, or anyone who loves working in the terminal.

Core Concepts

Apicentric is built around a few core concepts:

Service Definition: A YAML file that defines a mock API, including its endpoints, responses, and scenarios.
Simulator: A local server that serves the mock APIs defined in your service definitions.
Contract Testing: A feature that allows you to validate that your mock APIs match the real APIs they are mocking.
Code Generation: A feature that allows you to generate client code from your service definitions.
TUI: A terminal user interface that provides a visual way to manage your services.

Quick Start

Get up and running in 5 minutes:

# Install
brew install pmaojo/tap/apicentric

# Create a service
cat > my-api.yaml << EOF
name: my-api
server:
  port: 9000
  base_path: /api
endpoints:
  - method: GET
    path: /hello
    responses:
      200:
        content_type: application/json
        body: '{"message": "Hello, World!"}'
EOF

# Start simulator
apicentric simulator start --services-dir .

# Test it
curl http://localhost:9000/api/hello

Installation

Apicentric provides multiple installation methods to suit your workflow. Choose the one that works best for you.

Homebrew (macOS/Linux) - Recommended

The easiest way to install on macOS and Linux:

brew install pmaojo/tap/apicentric

Verify installation:

apicentric --version

Update to latest version:

brew upgrade apicentric

Install Script (Unix)

Quick installation script for Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.sh | sh

This script will:

Detect your platform and architecture automatically
Download the appropriate binary
Verify checksums for security
Install to /usr/local/bin (requires sudo)

Custom installation directory:

INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.sh | sh

Verify installation:

apicentric --version

Windows PowerShell

For Windows users, use the PowerShell installation script:

irm https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.ps1 | iex

This script will:

Download the Windows x64 binary
Verify checksums
Extract to %USERPROFILE%\.apicentric\bin
Add to PATH (restart terminal after installation)

Verify installation:

apicentric --version

Cargo (Build from Source)

If you have Rust installed, you can build from source with custom features:

Minimal build (fastest, ~1 minute):

cargo install apicentric --no-default-features --features minimal

Includes: Core simulator only

CLI Tools build (recommended, ~2 minutes):

cargo install apicentric --features cli-tools

Includes: Simulator, contract testing, and TUI

Full build (all features, ~3-5 minutes):

cargo install apicentric --features full

Includes: All features (TUI, P2P, GraphQL, scripting, AI)

Default build:

cargo install apicentric

Includes: Simulator and contract testing

Verify installation:

apicentric --version

Pre-built Binaries

Download pre-built binaries for your platform from GitHub Releases.

Available platforms:

Linux x64 (apicentric-linux-x64.tar.gz)
macOS x64 (apicentric-macos-x64.tar.gz)
macOS ARM64 (apicentric-macos-arm64.tar.gz)
Windows x64 (apicentric-windows-x64.zip)

Manual installation (Linux/macOS):

# Download the appropriate archive
curl -LO https://github.com/pmaojo/apicentric/releases/latest/download/apicentric-linux-x64.tar.gz

# Verify checksum (optional but recommended)
curl -LO https://github.com/pmaojo/apicentric/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing

# Extract
tar -xzf apicentric-linux-x64.tar.gz

# Move to PATH
sudo mv apicentric /usr/local/bin/

# Make executable
sudo chmod +x /usr/local/bin/apicentric

Manual installation (Windows):

Download apicentric-windows-x64.zip from releases
Extract the archive
Move apicentric.exe to a directory in your PATH
Or add the directory to your PATH environment variable

Verify installation:

apicentric --version

Docker (Coming Soon)

Docker images will be available soon for containerized deployments.

Verification

After installation, verify that Apicentric is working correctly:

# Check version
apicentric --version

# View help
apicentric --help

# List available commands
apicentric simulator --help

Expected output should show version information and available commands.

Troubleshooting

Command not found

Issue: apicentric: command not found after installation

Solutions:

Homebrew: Ensure Homebrew's bin directory is in your PATH:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

Install script: Verify /usr/local/bin is in your PATH:

echo $PATH | grep -q "/usr/local/bin" && echo "✓ In PATH" || echo "✗ Not in PATH"

Windows: Restart your terminal or PowerShell after installation to refresh PATH

Cargo: Ensure ~/.cargo/bin is in your PATH:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission denied

Issue: Permission errors during installation

Solutions:

Unix install script: The script requires sudo for /usr/local/bin. Use custom directory:

INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.sh | sh

Then add to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Manual installation: Use sudo when moving to system directories:

sudo mv apicentric /usr/local/bin/
sudo chmod +x /usr/local/bin/apicentric

Checksum verification failed

Issue: Checksum mismatch during installation

Solutions:

Download may be corrupted. Delete and try again:

rm apicentric-*.tar.gz
curl -LO https://github.com/pmaojo/apicentric/releases/latest/download/apicentric-linux-x64.tar.gz

Verify you're downloading from the official repository
Check your internet connection

Cargo build fails

Issue: Compilation errors when building from source

Solutions:

Update Rust: Ensure you have the latest stable Rust:
```
rustup update stable
```
Missing dependencies: Install required system dependencies:
- Ubuntu/Debian:
```
sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev
```
- macOS:
```
xcode-select --install
```
- Windows: Install Visual Studio Build Tools

Try minimal build: If full build fails, try minimal:

cargo install apicentric --no-default-features --features minimal

Feature not available

Issue: Command shows "Feature not available in this build"

Solutions:

You installed a minimal build. Reinstall with desired features:
```
cargo install apicentric --features cli-tools --force
```

Or install full version:

brew reinstall apicentric  # Homebrew includes cli-tools features

macOS security warning

Issue: "apicentric cannot be opened because it is from an unidentified developer"

Solutions:

Option 1: Use Homebrew installation (recommended):
```
brew install pmaojo/tap/apicentric
```

Option 2: Allow the binary manually:

xattr -d com.apple.quarantine /usr/local/bin/apicentric

Option 3: Build from source with Cargo:

cargo install apicentric --features cli-tools

Still having issues?

If you're still experiencing problems:

Check GitHub Issues for similar problems
Create a new issue with:
- Your operating system and version
- Installation method used
- Complete error message
- Output of apicentric --version (if available)
Join our Discussions for community support

Features

🎯 API Simulator

Define mock APIs in YAML and serve them locally:

Path parameters and regex matching
Dynamic templates with Handlebars
Scenarios for different states
Request/response logging
Request recording proxy and auto-generated endpoints via record_unknown
Imports OpenAPI 2.0/3.x specs, preferring documented examples and generating JSON bodies from schemas when necessary

✅ Contract Testing

Validate that mocks match real APIs:

Register contracts from specs
Compare mock vs real responses
HTML reports with differences
CI/CD integration

🔄 Code Generation

Generate client code from service definitions:

TypeScript interfaces
React Query hooks
OpenAPI specs
Postman collections

🖥️ TUI (Terminal User Interface)

Interactive terminal dashboard for service management:

Real-time service status
Live request logs with filtering
Start/stop services
Keyboard-driven workflow

🌐 Advanced Features (Optional)

P2P Collaboration: Share services with team members
GraphQL Mocking: Mock GraphQL APIs with schema
JavaScript Plugins: Extend with custom logic

Documentation

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

apicentric 0.1.1

Apicentric

What is Apicentric?

Core Concepts

Quick Start

Installation

Homebrew (macOS/Linux) - Recommended

Install Script (Unix)

Windows PowerShell

Cargo (Build from Source)

Pre-built Binaries

Docker (Coming Soon)

Verification

Troubleshooting

Command not found

Permission denied

Checksum verification failed

Cargo build fails

Feature not available

macOS security warning

Still having issues?

Features

🎯 API Simulator

✅ Contract Testing

🔄 Code Generation

🖥️ TUI (Terminal User Interface)

🌐 Advanced Features (Optional)

Documentation

Contributing

License

Community