# ExecuteSoft CLI
`exe` is the Rust command-line tool for ExecuteSoft repository automation. Keep
workflow logic here instead of adding new Bash or Makefile implementations.
## Source Layout
- `src/main.rs`: binary entrypoint only.
- `src/cli.rs`: Clap command, subcommand, and argument definitions.
- `src/commands.rs`: top-level command dispatch, sync, release, and deployment.
- `src/service.rs`: service generation, service discovery, and compliance checks.
- `src/gateway.rs`: gateway route generation wrappers and route source validation.
- `src/db.rs`: database migration helper commands.
- `src/dev.rs`: service-local dev, explicit compose helpers, and polling watch helper.
- `src/service_local.rs`: service-only checkout setup and dev runner.
- `src/util.rs`: shared repository path, process, and Make variable helpers.
- `src/tests.rs`: focused CLI, generator, compliance helper, and help-output tests.
## Local Use
From the repository root, build the local binary:
```bash
make cli
```
Run it from `bin/exe`:
```bash
./bin/exe service check-all
./bin/exe service create --name recommendation-engine --domain core --template rust
./bin/exe gateway generate
./bin/exe setup
./bin/exe dev
./bin/exe dev up DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
```
Run without building `bin/exe`:
```bash
cargo run -p executesoft --bin exe -- service check-all
```
Install for the current user:
```bash
cargo install --path tools/exe
exe service check-all
```
If `exe` is not found after installation, add Cargo binaries to the shell path:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
## Use Cases
### Check Service Compliance
Use this before committing service or template changes:
```bash
exe service check services/core/auth
exe service check-all
```
`check-all` validates service roots under `services/` and certified template
skeletons under `tools/templates/`.
### Service-Only Checkout
Use this flow for developers who only receive one service repository or folder:
```bash
git clone <service-repo>
cd <service-repo>
exe setup
exe dev
```
`exe setup` walks upward to find `service.yaml`, validates the service contract,
runs the local generator when one exists, downloads language dependencies, and
starts `development/compose.dev.yml` dependencies. Pass setup variables as
`key=value` pairs when needed:
```bash
exe setup SKIP_DOCKER=1
exe setup SKIP_DEPS=1
exe setup SKIP_GENERATE=1
```
Plain `exe dev` runs inside a service checkout. It starts service-local Docker
dependencies, loads `configs/app.env.example`, watches the service directory,
and runs the command implied by `service.yaml`:
- Go: `go run ./cmd/server`
- Rust: `cargo run`
- TypeScript: `bun run dev` or `npm run dev` when a `dev` script exists
- Python: `python -m src.server`
### Create A Service
Use the generator instead of copying service folders manually:
```bash
exe service create \
--name recommendation-engine \
--domain core \
--template rust \
--owner-team team-recommendation-engine
```
The generator copies the selected certified template, replaces template tokens,
creates the service folder, and creates the shared protobuf contract when the
local service contract exists.
### Run Service Make Targets
Use service names for common operations:
```bash
exe service test auth
exe service build gateway
exe service generate notification
exe service clippy services/core/auth
```
When a service name is ambiguous, pass the service path.
### Manage Gateway Routes
Generated gateway artifacts must come from route source files and protobufs:
```bash
exe gateway route create --service auth
exe gateway route from-proto --service auth
exe gateway route entry --service auth --rpc Login
exe gateway generate
```
Do not manually edit generated route artifacts.
### Run Local Development Helpers
```bash
exe dev
exe dev up DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
exe dev all DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
exe dev down DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
exe dev logs DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
exe dev watch -- cargo run
```
Plain `exe dev` is the normal service-local flow. Compose subcommands require
an explicit `DEV_COMPOSE_FILE`. Use `dev watch` for simple polling reloads in
services that need it.
### Release And Deployment
`release` and deployment commands keep repository sync first-class:
```bash
exe sync
exe release tag=latest
exe release-sync
exe deploy kubernetes tag=latest
exe deploy docker tag=latest
exe deploy migrations
exe deploy backup-now
exe deploy release-sync
exe deploy reload-caddy
exe deploy restart-cdn
exe deploy recreate CONTAINER=cdn
```
`deploy kubernetes` runs `sync` before delegating to the deployment Make target.
## crates.io Publishing
The crate is publish-enabled in `tools/exe/Cargo.toml`:
```toml
publish = true
```
To publish, first update `tools/exe/Cargo.toml` with public package metadata:
```toml
[package]
name = "executesoft"
version = "0.1.0"
edition = "2024"
rust-version = "1.95"
description = "ExecuteSoft repository automation CLI"
license = "MIT"
repository = "https://github.com/execute-soft/executsoft"
readme = "README.md"
publish = true
```
The package name is global on crates.io. If `executesoft` is unavailable,
choose another package name. The installed binary can still be named `exe`
because the binary target controls the command name:
```toml
[[bin]]
name = "exe"
path = "src/main.rs"
```
Authenticate and verify:
```bash
cargo login
cargo package --manifest-path tools/exe/Cargo.toml --list
cargo publish --manifest-path tools/exe/Cargo.toml --dry-run
```
Publish:
```bash
cargo publish --manifest-path tools/exe/Cargo.toml
```
After publishing, install from crates.io:
```bash
cargo install executesoft
exe service check-all
```
For private company tooling, prefer local or private-registry installation until
the command surface and package metadata are stable.