<img src="assets/Vertical_Logo.svg" alt="Jarvy" width="200" />
[](https://github.com/bearbinary/jarvy/actions/workflows/test.yml)
[](https://codecov.io/gh/bearbinary/jarvy)
[](https://securityscorecards.dev/viewer/?uri=github.com/bearbinary/jarvy)
[](LICENSE)
# Jarvy
**Jarvy** is a fast, cross-platform CLI that standardizes and automates local development environment setup from a declarative `jarvy.toml` config file. It installs 200+ tools using native package managers (Homebrew, apt, dnf, winget, Chocolatey) and ensures every team member has an identical development environment -- no cloud VMs, no containers, no recurring costs.
## Why Jarvy?
- **Instant onboarding** -- New developers run one command and get a fully configured workstation in seconds, not days
- **Dev environment as code** -- `jarvy.toml` is version-controlled, replacing wiki pages and tribal knowledge
- **Cross-platform** -- Same config works on macOS, Linux, and Windows using native package managers
- **Local and offline** -- No cloud dependency, no container overhead, full native performance
- **Safe and idempotent** -- Run repeatedly; Jarvy detects what's already installed and skips it
- **200+ tools supported** -- From git and docker to terraform, kubectl, and language runtimes
## Installation
```bash
# With Cargo
cargo install jarvy
# With Homebrew (macOS/Linux)
brew install jarvy
# Or download a binary from GitHub Releases
# https://github.com/bearbinary/jarvy/releases
```
Verify installation:
```bash
jarvy --version
```
### Early-Release Channel (Opt-In)
Jarvy ships pre-release tags (`-rc.N`, `-beta.N`) to a separate channel so
you can validate fixes and features before they land in stable. Opt in any
of three ways — all are reversible.
**On install** — set `JARVY_CHANNEL` before running the install script:
```bash
# Unix
JARVY_CHANNEL=beta curl -fsSL \
# Windows PowerShell
$env:JARVY_CHANNEL = 'beta'
**Per-update** — pass `--channel`:
```bash
jarvy update --channel beta
```
**Persistent** — set in `~/.jarvy/config.toml`:
```toml
[update]
Channel semantics:
| `stable` | Only `vX.Y.Z` tags |
| `beta` | `vX.Y.Z`, `vX.Y.Z-rc.N`, `vX.Y.Z-beta.N` |
| `nightly` | Everything including `-alpha.N` |
Opting into `beta` is the easiest way to help validate releases. Issues
tagged `release-blocker` or `regression` filed against a pre-release block
its promotion to stable — see
[`docs/release-testing.md`](docs/release-testing.md) for the full process.
## Quick Start
### 1. Create a config
```bash
# Interactive wizard
jarvy init
# Or from a template
jarvy init --template react
jarvy init --template rust-cli
jarvy init --template python-api
jarvy init --template k8s-admin
```
Or create `jarvy.toml` manually in your project root:
```toml
[privileges]
use_sudo = false
[provisioner]
git = "latest"
node = "20"
docker = "latest"
jq = "latest"
```
### 2. Run setup
```bash
jarvy setup
```
Output:
```
Setting up development environment...
[OK] git 2.44.0 (installed: 2.44.0) - satisfies requirement
[INSTALL] node 20 - installing via brew...
[OK] node 20.11.1 installed successfully
[OK] docker 25.0.3 (installed: 25.0.3) - satisfies requirement
[INSTALL] jq latest - installing via brew...
[OK] jq 1.7.1 installed successfully
Setup complete: 4 tools (2 installed, 2 already satisfied)
```
### 3. Share with your team
Commit `jarvy.toml` to your repository. Add to your project's README:
```bash
# Set up development environment
cargo install jarvy && jarvy setup
```
## Configuration
Jarvy supports simple and detailed tool specifications:
```toml
[privileges]
use_sudo = false
[provisioner]
# Simple: tool = "version"
git = "latest"
node = "20"
python = "3.12"
docker = "latest"
# Detailed: tool = { version, version_manager }
rust = { version = "stable", version_manager = true }
# Role-based tool sets
[roles.frontend]
description = "Frontend development"
tools = ["node", "bun", "typescript"]
[roles.devops]
description = "DevOps/Platform engineering"
extends = "base"
tools = ["kubectl", "terraform", "docker", "helm"]
# Post-install hooks
[hooks]
post_setup = "echo 'Environment ready!'"
[hooks.node]
post_install = "corepack enable"
# Environment variables
[env.vars]
PROJECT_ROOT = "$PWD"
NODE_ENV = "development"
# Custom project commands (used by interactive menu)
[commands]
run = "npm start"
test = "npm test"
```
See [Configuration Reference](docs/configuration.md) for all options including environment variables, secrets, services, drift detection, network/proxy settings, and git configuration.
## Shell Completions
Jarvy supports tab completions for all major shells:
```bash
# Bash
jarvy completions bash >> ~/.bashrc
# Zsh
jarvy completions zsh >> ~/.zshrc
# Fish
jarvy completions fish > ~/.config/fish/completions/jarvy.fish
# PowerShell
jarvy completions powershell >> $PROFILE
```
Or view installation instructions for your shell:
```bash
jarvy completions --instructions
```
## Key Commands
| `jarvy setup` | Install all tools from `jarvy.toml` |
| `jarvy init` | Create a new config interactively or from a template |
| `jarvy doctor` | Health-check your environment |
| `jarvy validate` | Validate a `jarvy.toml` file |
| `jarvy diff` | Show what's installed vs. what's needed |
| `jarvy drift check` | Detect environment drift from baseline |
| `jarvy tools` | List all 200+ supported tools |
| `jarvy templates list` | Browse available project templates |
| `jarvy completions` | Generate shell completions |
| `jarvy diagnose` | Create a diagnostic bundle for support |
| `jarvy mcp` | Start the MCP server for AI agent integration |
Run `jarvy --help` for the full command reference.
## Use in CI/CD
### GitHub Actions
```yaml
jobs:
setup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Jarvy
uses: bearbinary/jarvy/.github/actions/setup-jarvy@main
with:
method: cargo
- run: jarvy setup --ci
```
The `--ci` flag enables non-interactive mode with CI-provider detection (GitHub Actions, GitLab CI, CircleCI, Azure DevOps, Jenkins, Bitbucket).
## Scaffold a New Tool
Contributors can add tool support using the built-in scaffolding command:
```bash
# Creates src/tools/mytool/ with the define_tool! macro template
cargo run -p cargo-jarvy -- new-tool mytool
# Or if cargo-jarvy is installed:
cargo jarvy new-tool mytool
```
## AI/LLM Integration
Jarvy includes a built-in [MCP server](docs/mcp-server.md) that lets AI agents discover, check, and install tools via JSON-RPC:
```bash
jarvy mcp
```
For AI agents and LLMs, see [llms.txt](llms.txt) for a structured reference optimized for machine consumption.
## Documentation
- [Quickstart Guide](docs/quickstart.md)
- [Configuration Reference](docs/configuration.md)
- [CLI Reference](docs/cli.md)
- [Hooks](docs/hooks.md)
- [Adding Tools](docs/adding-tools.md)
- [CI/CD Integration](docs/ci-cd.md)
- [MCP Server](docs/mcp-server.md)
- [FAQ](docs/faq.md)
- [Privacy Policy](PRIVACY.md)
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
```bash
# Build
cargo build
# Test
cargo test --verbose -- --show-output
# Lint
cargo fmt --all && cargo clippy --all-features -- -D warnings
# Scaffold a new tool
cargo run -p cargo-jarvy -- new-tool <name>
```
## License
Dual-licensed under [MIT](LICENSE) or [Apache-2.0](LICENSE), at your option.
---