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:

make cli

Run it from bin/exe:

./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:

cargo run -p executesoft --bin exe -- service check-all

Install for the current user:

cargo install --path tools/exe
exe service check-all

If exe is not found after installation, add Cargo binaries to the shell path:

export PATH="$HOME/.cargo/bin:$PATH"

Use Cases

Check Service Compliance

Use this before committing service or template changes:

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:

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:

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:

POSTGRES_PORT=15432 REDIS_PORT=16379 NATS_PORT=14222 exe dev up

Create A Service

Use the generator instead of copying service folders manually:

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:

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:

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

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:

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:

publish = true

To publish, first update tools/exe/Cargo.toml with public package metadata:

[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:

[[bin]]
name = "exe"
path = "src/main.rs"

Authenticate and verify:

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:

exe publish --allow-dirty

After publishing, install from crates.io:

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.