# 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
```
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 the shared local dependency stack. 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 shared 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`
Several services can run locally at once because they share the same Postgres,
Redis, NATS, and MongoDB containers. Postgres isolation is by database name.
Override shared dependency ports only when needed:
```bash
POSTGRES_PORT=15432 REDIS_PORT=16379 NATS_PORT=14222 exe dev up
```
### 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
exe dev all
exe dev down
exe dev logs
exe dev watch -- cargo run
```
Plain `exe dev` is the normal service-local flow. Compose subcommands use the
shared local dependency stack by default. 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.