# 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 config set-root --path /path/to/executesoft
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"
```
## Global Developer Setup
Use this on every developer machine that has a full ExecuteSoft repository
checkout:
```bash
git clone <executesoft-repo-url> executesoft
cd executesoft
cargo install --path tools/exe --force
exe config set-root --path "$(pwd)"
exe config root
```
After that, `exe` works from any terminal directory because it can resolve the
configured repository root:
```bash
cd ~/Developer
exe service create --name recommendation-engine --domain core --template rust
exe service check-all
exe gateway generate
exe sync
```
You can also avoid persistent config by setting `EXECUTESOFT_ROOT`:
```bash
export EXECUTESOFT_ROOT=/path/to/executesoft
```
## 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.
`exe dev up` creates missing local Postgres databases dynamically by scanning
service env examples and Makefile `MIGRATION_DB_NAME` values. There is no
hard-coded service database list, so new services are picked up without
changing the shared compose file.
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 CONTAINER=<compose-service-name>
exe deploy recreate CONTAINER=<compose-service-name>
```
`deploy kubernetes` runs `sync` before delegating to the deployment Make target.
`sync` prunes gateway route imports for removed services, deletes stale route
source files whose target proto no longer exists, removes orphan shared service
protobufs, regenerates gateway artifacts, refreshes Swagger/OpenAPI and
generated API reference pages, then runs DevOps service asset sync.
## 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 through `exe` so the crate patch version is bumped before Cargo runs.
Pass normal `cargo publish` flags after the command:
```bash
exe publish --allow-dirty
```
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.