Try Live
Add Docs
Rankings
Pricing
Docs
Install
Install
Docs
Pricing
More...
More...
Try Live
Rankings
Enterprise
Create API Key
Add Docs
Razd
https://github.com/razd-cli/razd
Admin
Razd is a modern project setup tool that orchestrates mise and taskfile for one-command project
...
Tokens:
18,695
Snippets:
148
Trust Score:
2.7
Update:
4 months ago
Context
Skills
Chat
Benchmark
88
Suggestions
Latest
Show doc for...
Code
Info
Show Results
Context Summary (auto-generated)
Raw
Copy
Link
# Razd - Project Setup and Development Orchestration Tool Razd is a modern CLI tool designed to streamline project initialization and development workflows. It orchestrates `mise` (a polyglot version/environment manager) and `taskfile` (a task runner) to provide one-command project setup. Written in Rust, it serves both as a command-line utility and a library for testing and integration purposes. The tool automates the entire project lifecycle from cloning repositories, installing development tools, setting up dependencies, to running development and build workflows. The project addresses the common pain point of inconsistent development environment setup by providing a unified configuration format (Razdfile.yml) that combines tool management and task automation. It automatically synchronizes configuration between Razdfile.yml and mise.toml, ensuring consistency while supporting both simple and complex tool configurations. With built-in project type detection and template generation, Razd can quickly bootstrap new projects with sensible defaults for Node.js, Python, Rust, Go, and other ecosystems. ## CLI Commands ### razd up - Initialize and Setup Projects Clone a repository and set it up, or initialize/setup a local project. Supports three modes: clone mode (with URL), local mode (no URL), and init mode (--init flag). ```bash # Clone and setup a remote repository razd up https://github.com/user/project.git # Clone with custom directory name razd up https://github.com/user/project.git --name my-project # Setup existing local project cd my-project razd up # Initialize new Razdfile.yml with project detection razd up --init # Example output: # Setting up project from https://github.com/user/nodejs-app.git # Cloning repository... # Working in directory: /home/user/nodejs-app # Installing development tools with mise # Successfully installed development tools # Running default workflow... # ✓ Project setup completed successfully! ``` ### razd install - Install Development Tools Install all development tools defined in Razdfile.yml or mise.toml using mise. ```bash # Install all tools from configuration razd install # Skip automatic sync between Razdfile.yml and mise.toml razd install --no-sync # Example with Razdfile.yml containing: # mise: # tools: # node: "22" # python: "3.11" # plugins: # node: "https://github.com/asdf-vm/asdf-nodejs.git" # Output: # Installing development tools with mise # Installing node@22... # Installing python@3.11... # Successfully installed development tools ``` ### razd setup - Install Project Dependencies Install project dependencies using taskfile. Executes the "setup" task defined in Razdfile.yml. ```bash # Run project setup (npm install, pip install, cargo build, etc.) razd setup # Example for Node.js project: # Running project setup... # npm install # added 247 packages in 5s # ✓ Project dependencies installed successfully! # Example for Python project: # Running project setup... # pip install -r requirements.txt # Successfully installed 42 packages # ✓ Project dependencies installed successfully! ``` ### razd dev - Start Development Workflow Start the development server or workflow. Executes the "dev" task with interactive output. ```bash # Start development server razd dev # Example for Node.js project with this Razdfile.yml: # tasks: # dev: # desc: Start development server # cmds: # - npm run dev # Output (interactive): # > app@1.0.0 dev # > next dev # ▲ Next.js 14.0.0 # - Local: http://localhost:3000 # ✓ Ready in 2.3s ``` ### razd build - Build Project Build the project using the configured build workflow. ```bash # Build project razd build # Example for Rust project: # Building project... # Compiling razd v0.4.2 # Finished release [optimized] target(s) in 45.23s # ✓ Build completed successfully! # Example for Node.js project: # Building project... # npm run build # Creating optimized production build... # ✓ Build completed successfully! ``` ### razd run - Execute Custom Tasks Execute any custom task defined in Razdfile.yml with optional arguments. ```bash # Run custom task razd run test # Run task with arguments razd run deploy --args "--env=production" # Example Razdfile.yml: # tasks: # test: # desc: Run test suite # cmds: # - cargo test # deploy: # desc: Deploy application # cmds: # - ./scripts/deploy.sh {{.CLI_ARGS}} # Output: # Running custom task: test # running 15 tests # test result: ok. 15 passed; 0 failed ``` ## Configuration Format ### Razdfile.yml Structure Complete configuration file supporting mise tools, plugins, and taskfile tasks. ```yaml # Razdfile.yml - Project configuration version: '3' # Mise configuration for tool management mise: # Simple tool versions tools: node: "22" python: "3.11" task: "latest" # Complex tool configuration with options go: version: "1.21" postinstall: "go install golang.org/x/tools/cmd/goimports@latest" os: ["linux", "macos"] install_env: CGO_ENABLED: "1" GOARCH: "amd64" # Custom mise plugins plugins: node: "https://github.com/asdf-vm/asdf-nodejs.git" elixir: "https://github.com/my-org/mise-elixir.git#v1.0.0" # Task definitions (Taskfile v3 format) tasks: # Primary setup task (executed by "razd up") default: desc: Set up and start project cmds: - task: install - task: setup - task: dev # Install development tools install: desc: Install development tools via mise cmds: - mise install - echo "Tools installed successfully" # Setup project dependencies setup: desc: Install project dependencies cmds: - npm install - npm run build # Development workflow dev: desc: Start development server cmds: - npm run dev # Build workflow build: desc: Build project for production cmds: - npm run build - npm run test # Custom task with variables deploy: desc: Deploy to environment cmds: - task: build vars: ENV: production VERSION: "{{.VERSION | default \"v1.0.0\"}}" - ./scripts/deploy.sh {{.ENV}} {{.VERSION}} # Internal task (hidden from task list) cleanup: desc: Internal cleanup task internal: true cmds: - rm -rf dist/ - rm -rf node_modules/ ``` ### Project Type Detection and Templates Auto-generate Razdfile.yml based on detected project type with appropriate defaults. ```bash # Detect and initialize for Node.js project cd my-nodejs-app razd up --init # Detected project type: Node.js # Creates this Razdfile.yml: # mise: # tools: # node: "22" # task: "latest" # plugins: # node: "https://github.com/asdf-vm/asdf-nodejs.git" # # tasks: # default: # desc: Set up and start Node.js project # cmds: # - task: install # - task: dev # install: # desc: Install dependencies # cmds: # - mise install # - npm install # dev: # desc: Start development server # cmds: # - npm run dev # build: # desc: Build project # cmds: # - npm run build # test: # desc: Run tests # cmds: # - npm test # Supported project types: # - Node.js (detects: package.json) # - Python (detects: requirements.txt, pyproject.toml, setup.py) # - Rust (detects: Cargo.toml) # - Go (detects: go.mod) # - Docker (detects: Dockerfile) # - Generic (fallback) ``` ## Library API ### Load and Parse Configuration Load Razdfile.yml from filesystem and access configuration programmatically. ```rust use razd::config::RazdfileConfig; use razd::core::Result; use std::path::Path; // Load from current directory let config = RazdfileConfig::load()?; if let Some(razdfile) = config { println!("Version: {}", razdfile.version); // Access mise configuration if let Some(mise) = razdfile.mise { if let Some(tools) = mise.tools { for (name, tool_config) in tools.iter() { println!("Tool: {}", name); } } } // Check for tasks if razdfile.has_task("dev") { println!("Dev task exists"); } // Get primary task for "razd up" if let Some(primary) = razdfile.get_primary_task() { println!("Primary task: {}", primary); } } // Load from specific path let config = RazdfileConfig::load_from_path("/path/to/Razdfile.yml")?; // Example usage with error handling match RazdfileConfig::load() { Ok(Some(config)) => { // Process configuration for (task_name, task_config) in config.tasks.iter() { if let Some(desc) = &task_config.desc { println!("{}: {}", task_name, desc); } } }, Ok(None) => println!("No Razdfile.yml found"), Err(e) => eprintln!("Failed to load config: {}", e), } ``` ### Tool Installation via Mise Integration Install development tools programmatically using mise integration. ```rust use razd::integrations::mise; use std::path::Path; #[tokio::main] async fn main() -> razd::Result<()> { let project_dir = Path::new("."); // Install all tools from mise configuration mise::install_tools(project_dir).await?; // Install specific tool with version mise::install_specific_tool("node", "22", project_dir).await?; // Check if mise configuration exists if mise::has_mise_config(project_dir) { println!("Mise configuration found"); } // Fast-path: ensure tool is available (skips if already installed) mise::ensure_tool_available("node", "22", project_dir).await?; Ok(()) } // Example: Install tools and handle errors async fn setup_environment(dir: &Path) -> razd::Result<()> { use razd::core::output; match mise::install_tools(dir).await { Ok(_) => { output::success("All tools installed successfully"); Ok(()) } Err(e) => { output::error(&format!("Failed to install tools: {}", e)); Err(e) } } } ``` ### Execute Commands and Workflows Execute system commands and taskfile workflows programmatically. ```rust use razd::integrations::process; use razd::integrations::taskfile; use std::path::Path; #[tokio::main] async fn main() -> razd::Result<()> { let working_dir = Path::new("."); // Execute command and capture output let output = process::execute_command( "npm", &["install"], Some(working_dir) ).await?; println!("npm install output: {}", output); // Execute command with interactive output (real-time) process::execute_command_interactive( "npm", &["run", "dev"], Some(working_dir) ).await?; // Check if command is available if process::check_command_available("mise").await { println!("mise is installed"); } // Execute taskfile workflow let workflow_content = r#" version: '3' tasks: build: cmds: - cargo build --release - echo "Build complete" "#; taskfile::execute_workflow_task( "build", workflow_content, working_dir ).await?; // Execute workflow interactively taskfile::execute_workflow_task_interactive( "dev", workflow_content, working_dir ).await?; // Check for Taskfile configuration if taskfile::has_taskfile_config(working_dir) { println!("Taskfile found in project"); } Ok(()) } ``` ### Configuration Synchronization Sync configuration between Razdfile.yml and mise.toml automatically. ```rust use razd::config::mise_sync::{MiseSyncManager, SyncConfig, SyncResult}; use std::path::PathBuf; // Create sync manager with default config let project_root = PathBuf::from("."); let config = SyncConfig::default(); let sync_manager = MiseSyncManager::new(project_root, config); // Check and sync if needed match sync_manager.check_and_sync_if_needed()? { SyncResult::NoChangesNeeded => { println!("Configuration already in sync"); } SyncResult::RazdfileToMise => { println!("Synced Razdfile.yml to mise.toml"); } SyncResult::MiseToRazdfile => { println!("Synced mise.toml to Razdfile.yml"); } SyncResult::Skipped => { println!("Sync skipped (--no-sync flag)"); } SyncResult::Conflict => { println!("Conflict detected - manual resolution needed"); } } // Custom sync configuration let custom_config = SyncConfig { no_sync: false, auto_approve: true, // Skip confirmation prompts create_backups: true, // Create .bak files before overwriting }; let sync_manager = MiseSyncManager::new(project_root, custom_config); let result = sync_manager.check_and_sync_if_needed()?; // Example: Helper function for sync use razd::config::mise_sync::check_and_sync_mise; async fn ensure_synced(project_dir: &Path) -> razd::Result<()> { // Simple sync check using helper function check_and_sync_mise(project_dir)?; Ok(()) } ``` ### Git Repository Operations Clone repositories and extract repository information. ```rust use razd::integrations::git; #[tokio::main] async fn main() -> razd::Result<()> { // Clone repository to default directory (repo name) let repo_path = git::clone_repository( "https://github.com/user/project.git", None ).await?; println!("Cloned to: {}", repo_path); // Clone to custom directory let custom_path = git::clone_repository( "https://github.com/user/project.git", Some("my-custom-name") ).await?; println!("Cloned to: {}", custom_path); // Extract repository name from URL let repo_name = git::extract_repo_name( "https://github.com/user/awesome-project.git" )?; assert_eq!(repo_name, "awesome-project"); // Works with different URL formats let name1 = git::extract_repo_name("git@github.com:user/repo.git")?; let name2 = git::extract_repo_name("https://gitlab.com/user/repo")?; Ok(()) } // Example: Clone and setup workflow async fn clone_and_setup(url: &str, dir_name: Option<&str>) -> razd::Result<()> { use std::env; use razd::config::get_workflow_config; use razd::integrations::taskfile; // Clone repository let repo_path = git::clone_repository(url, dir_name).await?; // Change to repository directory let absolute_path = env::current_dir()?.join(&repo_path); env::set_current_dir(&absolute_path)?; // Get and execute workflow if let Some(workflow) = get_workflow_config("default")? { taskfile::execute_workflow_task_interactive( "default", &workflow, &absolute_path ).await?; } Ok(()) } ``` ### Error Handling Comprehensive error types for all operations with helpful context. ```rust use razd::core::{RazdError, Result}; // Error variants and usage fn example_error_handling() -> Result<()> { // Git errors Err(RazdError::git("Failed to clone repository"))?; // Mise errors Err(RazdError::mise("Tool installation failed"))?; // Task errors Err(RazdError::task("Workflow execution failed"))?; // Configuration errors Err(RazdError::config("Invalid Razdfile.yml format"))?; // Missing tool with help URL Err(RazdError::missing_tool( "mise", "https://mise.jdx.dev/getting-started.html" ))?; // No project configuration found Err(RazdError::no_project_config( "Run 'razd up --init' to create a Razdfile.yml" ))?; // No default task Err(RazdError::no_default_task())?; // Invalid URL Err(RazdError::invalid_url("Not a valid git URL"))?; Ok(()) } // Pattern matching on errors async fn handle_operation() { match perform_setup().await { Ok(_) => println!("Setup successful"), Err(RazdError::MissingTool { tool, help }) => { eprintln!("Missing tool: {}", tool); eprintln!("Install from: {}", help); } Err(RazdError::NoProjectConfig { suggestion }) => { eprintln!("No configuration found"); eprintln!("Suggestion: {}", suggestion); } Err(e) => eprintln!("Error: {}", e), } } async fn perform_setup() -> Result<()> { // Implementation Ok(()) } // Example with multiple error points use razd::integrations::{mise, taskfile}; use std::path::Path; async fn full_setup_with_errors(dir: &Path) -> Result<()> { // Check mise availability if !razd::integrations::process::check_command_available("mise").await { return Err(RazdError::missing_tool( "mise", "https://mise.jdx.dev" )); } // Install tools (may fail) mise::install_tools(dir).await .map_err(|e| RazdError::mise(format!("Setup failed: {}", e)))?; // Setup project (may fail) taskfile::setup_project(dir).await .map_err(|e| RazdError::task(format!("Dependency install failed: {}", e)))?; Ok(()) } ``` ## Advanced Usage Patterns ### Custom Tool Configuration with Environment Variables Configure complex tool installations with platform-specific options. ```yaml # Razdfile.yml with advanced tool configuration mise: tools: # Simple version node: "22" # Complex configuration python: version: "3.11" postinstall: | pip install --upgrade pip setuptools wheel pip install poetry os: ["linux", "macos"] install_env: PYTHON_CONFIGURE_OPTS: "--enable-optimizations" ruby: version: "3.2.0" postinstall: "gem install bundler" install_env: RUBY_CONFIGURE_OPTS: "--with-openssl-dir=/usr/local/opt/openssl" go: version: "1.21" postinstall: | go install golang.org/x/tools/cmd/goimports@latest go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest install_env: CGO_ENABLED: "1" GOARCH: "amd64" tasks: default: cmds: - mise install - echo "Environment ready" ``` ### Task Composition with Variables Compose complex workflows from reusable tasks with variable passing. ```yaml # Razdfile.yml with task composition tasks: # Reusable tasks clean: desc: Clean build artifacts cmds: - rm -rf dist/ build/ *.egg-info/ lint: desc: Run linters cmds: - npm run lint - npm run format:check test: desc: Run test suite cmds: - npm run test -- --coverage build: desc: Build for specific environment cmds: - echo "Building for {{.ENV | default \"development\"}}" - npm run build -- --mode={{.ENV}} # Composite workflows ci: desc: Full CI pipeline cmds: - task: clean - task: lint - task: test - task: build vars: ENV: production deploy: desc: Deploy to environment cmds: - task: build vars: ENV: "{{.TARGET_ENV}}" - ./scripts/deploy.sh {{.TARGET_ENV}} {{.VERSION}} # Interactive development dev: desc: Development with watch mode cmds: - npm run dev -- --host={{.HOST | default "localhost"}} --port={{.PORT | default "3000"}} ``` Razd provides a comprehensive solution for project initialization and development workflow orchestration. By combining mise for tool management and taskfile for task automation under a unified Razdfile.yml configuration, it eliminates environment setup inconsistencies and reduces onboarding friction. The tool's automatic synchronization between Razdfile.yml and mise.toml ensures configuration stays consistent while giving developers flexibility to use either format. With intelligent project type detection, Razd can bootstrap new projects with appropriate templates and tool configurations for popular ecosystems. The library API enables integration into larger automation systems, custom CI/CD pipelines, or development environment managers. The comprehensive error handling with contextual messages helps developers quickly resolve issues, while the built-in workflow fallbacks ensure commands work even without a Razdfile.yml present. Whether used as a CLI tool for daily development or integrated as a library for custom tooling, Razd streamlines the entire project lifecycle from initial clone to production build.