Merge pull request #37 from NREL/updates

Improve CLI usability, documentation

Author: daniel-thom

CLAUDE.md

@@ -78,7 +78,7 @@ cd server
 
 # Build and run server (requires DATABASE_URL in .env)
 cargo build --release
-cargo run --bin torc-server
+cargo run --bin torc-server -- run
 
 # Run tests
 cargo test
@@ -291,7 +291,7 @@ List endpoints support `offset` and `limit` query parameters:
 
 **Server SQL Queries**:
 ```bash
-RUST_LOG=sqlx=debug cargo run --bin torc-server
+RUST_LOG=sqlx=debug cargo run --bin torc-server -- run
 ```
 
 **Client Verbose Output**:
@@ -317,13 +317,13 @@ sqlite3 server/db/sqlite/dev.db
 
 ## Development Workflow
 
-1. **Start Server** (standalone binary): `cargo run --bin torc-server`
+1. **Start Server** (standalone binary): `cargo run --bin torc-server -- run`
 2. **Build Unified CLI**: `cargo build --release --bin torc --features "client,tui,plot_resources"`
 3. **Quick Execution**: `torc run examples/sample_workflow.yaml` OR `torc submit examples/sample_workflow.yaml`
 4. **Or Explicit**: `torc workflows create examples/sample_workflow.yaml` → `torc workflows run <id>`
 5. **Monitor**: `torc workflows status <id>` or `torc tui`
 
-**Note**: The server is always run as a standalone binary (`torc-server`), not through the unified CLI.
+**Note**: The server is always run as a standalone binary (`torc-server run`), not through the unified CLI.
 
 ## CLI Commands Quick Reference
 

Cargo.toml

@@ -31,7 +31,7 @@ hdrhistogram = "7.5"
 signal-hook = "0.3"
 libc = "0.2"
 file-rotate = "0.7"
-clap = { version = "4.4", features = ["derive", "env"] }
+clap = { version = "4.4", features = ["derive", "env", "color"] }
 clap_complete = "4.4"
 tokio = { version = "1.47", features = ["rt-multi-thread", "macros", "net", "signal"] }
 url = "2.5"

README.md

@@ -46,9 +46,9 @@ The unified `torc` CLI provides all workflow management, execution, and monitori
 
 ```bash
 # 1. Start the Torc server (standalone binary)
-torc-server
+torc-server run
 # Or with options:
-torc-server --url localhost --port 8080 --threads 8 --database path/to/db.sqlite
+torc-server run --url localhost --port 8080 --threads 8 --database path/to/db.sqlite
 
 # 2. Use the unified CLI for all client operations
 # Create a workflow from a specification file

docs/src/SUMMARY.md

@@ -31,7 +31,6 @@
   - [Creating Workflows](./how-to/creating-workflows.md)
   - [Working with Slurm](./how-to/slurm.md)
   - [Job Checkpointing](./how-to/checkpointing.md)
-  - [Managing Resources](./how-to/resources.md)
   - [Resource Monitoring](./how-to/resource-monitoring.md)
   - [Web Dashboard](./how-to/dashboard.md)
   - [Debugging Workflows](./how-to/debugging.md)
@@ -45,6 +44,8 @@
   - [CLI Reference](./reference/cli.md)
   - [Workflow Specification Formats](./reference/workflow-formats.md)
   - [Job Parameterization](./reference/parameterization.md)
+  - [Resource Requirements](./reference/resources.md)
+  - [Resource Monitoring](./reference/resource-monitoring.md)
   - [OpenAPI Specification](./reference/openapi.md)
   - [Configuration](./reference/configuration.md)
   - [Security](./reference/security.md)

docs/src/how-to/README.md

@@ -1,16 +1,15 @@
 # How-To Guides
 
-This section provides problem-oriented guides for accomplishing specific tasks with Torc. Each guide walks through a concrete use case with step-by-step instructions.
+This section provides task-oriented guides for accomplishing specific goals with Torc. Each guide shows you how to complete a concrete task.
 
 **Topics covered:**
 
-- Creating workflows using different methods
-- Working with Slurm clusters
-- Checkpointing jobs during wall-time timeouts
-- Managing compute resources
-- Configuring resource requirements
-- Debugging workflow failures with log files
-- Monitoring workflow execution
-- Deploying and operating the server in production
-- Configuring logging and daemonization
-- Setting up authentication
+- [Creating Workflows](./creating-workflows.md) - Different methods for creating workflows
+- [Working with Slurm](./slurm.md) - Running workflows on Slurm clusters
+- [Job Checkpointing](./checkpointing.md) - Saving progress during wall-time timeouts
+- [Resource Monitoring](./resource-monitoring.md) - Tracking CPU and memory usage
+- [Web Dashboard](./dashboard.md) - Using the web-based monitoring interface
+- [Debugging Workflows](./debugging.md) - Troubleshooting workflow failures
+- [Authentication](./authentication.md) - Setting up user authentication
+- [Shell Completions](./shell-completions.md) - Enabling tab completion
+- [Server Deployment](./server-deployment.md) - Running the server in production

docs/src/how-to/authentication.md

@@ -50,14 +50,14 @@ bob:$2b$12$zyxwvutsrqponmlkjihgfedcba0987654321ZYXWVUTSRQPONMLK
 
 ```bash
 # Optional authentication (backward compatible mode)
-torc-server --auth-file /path/to/htpasswd
+torc-server run --auth-file /path/to/htpasswd
 
 # Required authentication (all requests must authenticate)
-torc-server --auth-file /path/to/htpasswd --require-auth
+torc-server run --auth-file /path/to/htpasswd --require-auth
 
 # Can also use environment variable
 export TORC_AUTH_FILE=/path/to/htpasswd
-torc-server
+torc-server run
 ```
 
 **Authentication Modes:**
@@ -129,7 +129,7 @@ Basic authentication sends base64-encoded credentials (easily decoded). **Always
 
 ```bash
 # Start server with HTTPS
-torc-server --https --auth-file /path/to/htpasswd --require-auth
+torc-server run --https --auth-file /path/to/htpasswd --require-auth
 
 # Client connects via HTTPS
 torc --url https://torc.example.com/torc-service/v1 --username alice workflows list
@@ -169,10 +169,10 @@ Monitor authentication events in server logs:
 
 ```bash
 # Run server with debug logging for auth events
-torc-server --log-level debug --auth-file /path/to/htpasswd
+torc-server run --log-level debug --auth-file /path/to/htpasswd
 
 # Or use RUST_LOG for granular control
-RUST_LOG=torc::server::auth=debug torc-server --auth-file /path/to/htpasswd
+RUST_LOG=torc::server::auth=debug torc-server run --auth-file /path/to/htpasswd
 ```
 
 ## Common Workflows
@@ -184,7 +184,7 @@ RUST_LOG=torc::server::auth=debug torc-server --auth-file /path/to/htpasswd
 torc-htpasswd add --file dev_htpasswd --password devpass developer
 
 # 2. Start server (auth optional)
-torc-server --auth-file dev_htpasswd --database dev.db
+torc-server run --auth-file dev_htpasswd --database dev.db
 
 # 3. Use client without auth (still works)
 torc workflows list
@@ -205,7 +205,7 @@ chmod 600 /etc/torc/htpasswd
 chown torc-server:torc-server /etc/torc/htpasswd
 
 # 3. Start server with required auth and HTTPS
-torc-server \
+torc-server run \
   --https \
   --auth-file /etc/torc/htpasswd \
   --require-auth \
@@ -238,16 +238,16 @@ torc workflows start "${WORKFLOW_ID}"
 
 ```bash
 # 1. Start: No authentication
-torc-server --database prod.db
+torc-server run --database prod.db
 
 # 2. Add authentication file (optional mode)
-torc-server --auth-file /etc/torc/htpasswd --database prod.db
+torc-server run --auth-file /etc/torc/htpasswd --database prod.db
 
 # 3. Monitor logs, ensure clients are authenticating
 # Look for "User 'X' authenticated successfully" messages
 
 # 4. Once all clients authenticate, enable required auth
-torc-server --auth-file /etc/torc/htpasswd --require-auth --database prod.db
+torc-server run --auth-file /etc/torc/htpasswd --require-auth --database prod.db
 ```
 
 ## Troubleshooting
@@ -284,7 +284,7 @@ torc-htpasswd add --file /path/to/htpasswd alice
 
 **Solution:** This is normal in optional auth mode. To require auth:
 ```bash
-torc-server --auth-file /path/to/htpasswd --require-auth
+torc-server run --auth-file /path/to/htpasswd --require-auth
 ```
 
 ### Password Prompting in Non-Interactive Sessions