Useful Tasks

Useful Tasks is a flexible CLI task runner that executes tasks defined in JSON or JSON5 configuration files. It was created to simplify workspace setup, automate repetitive steps, and manage complex dependencies—especially when working with multiple repositories or advanced file operations. Tasks are processed sequentially, and the tool supports a variety of built-in actions.

Support

Installation

Install Useful Tasks globally or as a dev dependency in your project:

• Globally:

  1npm install -g useful-tasks

• Locally (per project, as dependency):

  1npm install useful-tasks

• Locally (per project, as dev dependency):

  1npm install useful-tasks --save-dev

CLI Options

1useful-tasks --help

Supported Tasks

Useful Tasks supports a variety of actions, each defined as a task type in your configuration:

• cmd: Run shell commands
• output: Output text to console or file
• set-var: Define variables for use in later tasks. It supports glob patterns to match files.
• env-var: Set environment variables for task execution. It supports glob patterns to match files.
• fs-symlink: Create symbolic links
• fs-copy: Copy files or directories. It supports glob patterns to match files.
• fs-del: Delete files or directories. It supports glob patterns to match files.
• fs-mkdir: Create directories
• fs-touch: Create empty file
• git-setup: Set up a Git repository as desired, e.g., reset to the last commit or check out a specific branch; also supports a specific startPoint option.
• sub-tasks: Run another Useful Tasks configuration as a sub-process
• content-replace: Find and replace content in files. It supports glob patterns to match files.

How to Use

Useful Tasks is operated via CLI. Run the following for help:

1useful-tasks --help

Basic Usage

1useful-tasks --script=my_tasks.json

Include or Exclude Tasks by ID or Tag

1useful-tasks --script=my_tasks.json --include=task1,task2
2useful-tasks --script=my_tasks.json --exclude=task3

Pass Variables and Environment Variables

1useful-tasks --script=my_tasks.json --var-my-key=VALUE
2useful-tasks --script=my_tasks.json --env-MY_ENV=VALUE

Additional Options

• --cwd <dir>: Set working directory
• --camel-keys <bool>: Use camelCase for variable keys (default: true)
• --cwd-mode <restore|keep>: Restore or keep working directory after each task
• --log-level <none|info|debug>: Set logging verbosity

Scripting

Tasks are defined in a JSON or JSON5 file. Tasks are executed in the order they appear.

Task Object Structure

Each task can have the following properties:

• type (string, required): Task type (see Supported Tasks)
• id (string, optional): Unique identifier for referencing
• tags (string or array, optional): Tags for filtering tasks (can be a single string or array of strings)
• enabled (boolean, optional): If false, task is skipped (default: true)
• cwd (string, optional): Working directory for the task
• when (object, optional): Conditional execution based on platform, architecture, or machine.
  • platform (string, optional): Target platform (e.g., 'darwin', 'win32', 'linux', '!win32')
  • architecture (string, optional): Target architecture (e.g., 'x64', 'arm64', '!arm64')
  • machine (string, optional): Target machine (e.g., 'x86_64', 'arm64', '!arm64')
• comment (string, optional): Description or note
• onError (string, optional): Error handling strategy ('skip', 'throw', or 'warn', default: 'throw')

Examples

Minimal:

1{
2  "name": "Sample",
3  "tasks": [{ "type": "output", "text": "Hello world!" }]
4}

With various options:

1{
2  "name": "Sample",
3  "tasks": [
4    {
5      "type": "output",
6      "text": "Hello macos!",
7      "comment": "This is a comment",
8      "enabled": true,
9      "when": {
10        "platform": "darwin"
11      }
12    },
13    {
14      "type": "output",
15      "text": "Hello non windows!",
16      "comment": "This is a comment",
17      "enabled": true,
18      "when": {
19        "platform": "!win32"
20      }
21    },
22    {
23      "type": "output",
24      "text": "Hello linux!",
25      "comment": "This is a comment",
26      "enabled": true,
27      "when": {
28        "platform": "linux"
29      }
30    }
31  ]
32}

Environment and Global Options

1{
2  "name": "Sample",
3  "env": {
4    "logLevel": "info", // 'info', 'debug', or 'none' // Default: 'info'
5    // To replace variable literal in text properties of tasks. This Regex lets you replace `${variable.path}` with the value of the variable.
6    "varReplaceRegex": "(?<!\\\\)\\$\\{([a-zA-Z0-9\\.\\-_]*)\\}",
7    // To replace environment variable literal in text properties of tasks. This Regex lets you replace `${variable.path}` with the value of the environment variable.
8    "envVarReplaceRegex": "(?<!\\\\)\\$\\{([a-zA-Z0-9\\.\\-_]*)\\}"
9  },
10  "tasks": []
11}

Tasks

cmd

Runs shell commands with optional shell specification. Supports both single commands and arrays of commands that will run sequentially.

1{
2  "type": "cmd",
3  "cmd": "echo 'Hello World'",
4  "shell": "/bin/bash" // Optional, defaults to system shell
5}

Examples:

1// Simple command
2{
3  "type": "cmd",
4  "cmd": "npm install"
5}
6
7// Multiple commands (executed sequentially)
8{
9  "type": "cmd",
10  "cmd": [
11    "npm install",
12    "npm run build",
13    "npm test"
14  ]
15}
16
17// With working directory specified
18{
19  "type": "cmd",
20  "cmd": "ls -la",
21  "cwd": "./src"
22}
23
24// With conditional execution
25{
26  "type": "cmd",
27  "cmd": "brew update",
28  "when": {
29    "platform": "darwin"
30  }
31}

output

Outputs text to the console or a file.

1{
2  "type": "output",
3  "text": "Hello World",
4  "target": "console", // Optional: "console", "file-write", "file-append", "c", "fw", or "fa" (defaults to "console")
5  "path": "./output.txt" // Required if target is file-related
6}

Examples:

1// Console output
2{
3  "type": "output",
4  "target": "console",
5  "text": "Starting process..."
6}
7
8// Write to file (overwriting)
9{
10  "type": "output",
11  "target": "file-write", // or "fw"
12  "text": "Log entry: Process completed",
13  "path": "./logs/process.log"
14}
15
16// Append to file
17{
18  "type": "output",
19  "target": "file-append", // or "fa"
20  "text": "New log entry\n",
21  "path": "./logs/process.log"
22}

set-var

Defines variables for use in later tasks. Variables can be set directly or loaded from files.

1{
2  "type": "set-var",
3  "key": "variableName",
4  "value": "variableValue", // Can be string, number, boolean, or object
5  "isFallback": false // Optional, if true, won't overwrite existing variables
6}

Examples:

1// Simple variable
2{
3  "type": "set-var",
4  "key": "greeting",
5  "value": "Hello World"
6}
7
8// Object variable
9{
10  "type": "set-var",
11  "key": "config",
12  "value": {
13    "port": 3000,
14    "host": "localhost",
15    "debug": true
16  }
17}
18
19// Load from file
20{
21  "type": "set-var",
22  "key": "settings",
23  "src": "./config.json",
24  "parser": "json" // Options: "json", "lines", "string", "auto" (default)
25}
26
27// Load from multiple files using glob patterns
28{
29  "type": "set-var",
30  "key": "translations",
31  "src": "./locales",
32  "include": ["**/*.json"],
33  "exclude": ["**/*.backup.json"],
34  "parser": "json"
35}

env-var

Sets environment variables for the current process. Variables can be set directly or loaded from files.

1{
2  "type": "env-var",
3  "key": "ENV_VAR_NAME",
4  "value": "value",
5  "isFallback": false // Optional, if true, won't overwrite existing env vars
6}

Alternatively, you can set multiple environment variables at once:

1{
2  "type": "env-var",
3  "map": {
4    "NODE_ENV": "development",
5    "PORT": "3000",
6    "DEBUG": "true"
7  },
8  "isFallback": false
9}

Examples:

1// Simple environment variable
2{
3  "type": "env-var",
4  "key": "API_KEY",
5  "value": "secret-key-123"
6}
7
8// Load from .env file or other formats
9{
10  "type": "env-var",
11  "src": "./.env",
12  "parser": "lines" // Options: "json", "lines", "auto" (default)
13}
14
15// Load from multiple files using glob patterns
16{
17  "type": "env-var",
18  "src": "./configs",
19  "include": ["**/*.env"],
20  "exclude": ["**/*.local.env"],
21  "parser": "lines"
22}

fs-symlink

Creates symbolic links between files or directories.

1{
2  "type": "fs-symlink",
3  "target": "./source/path",
4  "path": "./link/path",
5  "linkType": "file", // Optional: "file", "dir", or "junction" (Windows only)
6  "forced": true // Optional: if true, will remove existing files/links at path
7}

Examples:

1// Create a simple symlink
2{
3  "type": "fs-symlink",
4  "target": "./actual/config.json",
5  "path": "./config.json"
6}
7
8// Create a directory symlink with forced overwrite
9{
10  "type": "fs-symlink",
11  "target": "./node_modules",
12  "path": "./vendor/modules",
13  "linkType": "dir",
14  "forced": true
15}

fs-copy

Copies files or directories with optional glob pattern filtering.

1{
2  "type": "fs-copy",
3  "src": "./source/directory",
4  "dest": "./destination/directory",
5  "options": {
6    "conflict": "overwrite" // Optional: "overwrite" or "skip"
7  },
8  "include": ["**/*.js"], // Optional: glob patterns to include
9  "exclude": ["**/*.test.js"] // Optional: glob patterns to exclude
10}

Examples:

1// Copy a single file
2{
3  "type": "fs-copy",
4  "src": "./config.json",
5  "dest": "./backup/config.json"
6}
7
8// Copy a directory with options
9{
10  "type": "fs-copy",
11  "src": "./src",
12  "dest": "./dist",
13  "options": {
14    "conflict": "skip"
15  }
16}
17
18// Copy specific files using glob patterns
19{
20  "type": "fs-copy",
21  "src": "./assets",
22  "dest": "./public/assets",
23  "include": ["**/*.{png,jpg,svg}"],
24  "exclude": ["**/temp/**"]
25}

fs-del

Deletes files or directories with optional glob pattern filtering.

1{
2  "type": "fs-del",
3  "path": "./path/to/delete",
4  "include": ["**/*.tmp"], // Optional: glob patterns to include
5  "exclude": ["**/*.important"] // Optional: glob patterns to exclude
6}

Examples:

1// Delete a single file
2{
3  "type": "fs-del",
4  "path": "./temp.log"
5}
6
7// Delete a directory
8{
9  "type": "fs-del",
10  "path": "./temp"
11}
12
13// Delete specific files using glob patterns
14{
15  "type": "fs-del",
16  "path": "./cache",
17  "include": ["**/*.cache"],
18  "exclude": ["**/important/**"]
19}

fs-mkdir

Creates directories. Supports both single paths and arrays of paths.

1{
2  "type": "fs-mkdir",
3  "path": "./path/to/create" // String or array of strings
4}

Examples:

1// Create a single directory
2{
3  "type": "fs-mkdir",
4  "path": "./logs"
5}
6
7// Create multiple directories
8{
9  "type": "fs-mkdir",
10  "path": [
11    "./logs",
12    "./data/cache",
13    "./temp/uploads"
14  ]
15}
16
17// Create nested directories
18{
19  "type": "fs-mkdir",
20  "path": "./data/cache/temp"
21}

fs-touch

Creates empty files. Supports both single paths and arrays of paths. Will not overwrite existing files.

1{
2  "type": "fs-touch",
3  "path": "./path/to/file.txt" // String or array of strings
4}

Examples:

1// Create an empty file
2{
3  "type": "fs-touch",
4  "path": "./logs/app.log"
5}
6
7// Create multiple empty files
8{
9  "type": "fs-touch",
10  "path": [
11    "./.gitkeep",
12    "./logs/errors.log",
13    "./temp/placeholder.txt"
14  ]
15}
16
17// Create a placeholder file
18{
19  "type": "fs-touch",
20  "path": "./.gitkeep"
21}

git-setup

Clones or updates a Git repository to a specific state.

1{
2  "type": "git-setup",
3  "localPath": "./path/to/repo",
4  "url": "https://github.com/user/repo.git",
5  "branch": "main",
6  "remote": "origin", // Optional, defaults to "origin"
7  "startPoint": "v1.0.0", // Optional, specific commit hash or tag to checkout
8  "checkLocalChanges": true, // Optional, whether to check for local changes
9  "updateSubmodules": true // Optional, can be boolean or array of submodule paths
10}

Examples:

1// Basic repository setup
2{
3  "type": "git-setup",
4  "localPath": "./projects/my-repo",
5  "url": "https://github.com/user/my-repo.git",
6  "branch": "main"
7}
8
9// Clone with specific tag and submodule handling
10{
11  "type": "git-setup",
12  "localPath": "./vendor/library",
13  "url": "https://github.com/org/library.git",
14  "branch": "stable",
15  "startPoint": "v2.1.0",
16  "updateSubmodules": ["./plugins/core", "./plugins/extra"]
17}
18
19// Development setup without checking local changes
20// This is so wild you can lose your local changes if you are not careful because 'checkLocalChanges' is false
21{
22  "type": "git-setup",
23  "localPath": "./dev/sandbox",
24  "url": "https://github.com/team/sandbox.git",
25  "branch": "develop",
26  "checkLocalChanges": false,
27  "updateSubmodules": false
28}

sub-tasks

Runs another task file or directory of task files as a sub-task group.

1{
2  "type": "sub-tasks",
3  "src": "./path/to/tasks.json",
4  "shareArgs": true, // Optional: whether to share CLI args with sub-tasks
5  "shareVars": true, // Optional: whether to share variables with sub-tasks
6  "args": "", // Optional: additional CLI args to pass to sub-tasks
7  "include": ["**/*.json"], // Optional: glob patterns to include
8  "exclude": ["**/*.skip.json"] // Optional: glob patterns to exclude
9}

Examples:

1// Run a single task file
2{
3  "type": "sub-tasks",
4  "src": "./setup/init.json"
5}
6
7// Run multiple task files with shared context
8{
9  "type": "sub-tasks",
10  "src": "./tasks",
11  "include": ["**/*.json"],
12  "exclude": ["**/temp/**"],
13  "shareVars": true,
14  "args": "--tags deploy"
15}
16
17// Run isolated sub-tasks without sharing variables
18{
19  "type": "sub-tasks",
20  "src": "./modules/cleanup.json",
21  "shareVars": false,
22  "shareArgs": false
23}

content-replace

Replaces content in files using string or regex patterns.

1{
2  "type": "content-replace",
3  "path": "./path/to/file.txt", // File or directory path
4  "find": "text to find", // String to find or regex object
5  "replace": "replacement text", // Replacement string
6  "loop": 1, // Optional: number of replacements to make (-1 for all occurrences)
7  "include": ["**/*.txt"], // Optional: glob patterns to include when path is a directory
8  "exclude": ["**/*.bak"] // Optional: glob patterns to exclude when path is a directory
9}

Examples:

1// Simple text replacement
2{
3  "type": "content-replace",
4  "path": "./config.json",
5  "find": "development",
6  "replace": "production"
7}
8
9// Replace all occurrences
10{
11  "type": "content-replace",
12  "path": "./README.md",
13  "find": "TODO",
14  "replace": "DONE",
15  "loop": -1 // Replace all occurrences
16}
17
18// Using regex
19{
20  "type": "content-replace",
21  "path": "./src",
22  "find": {
23    "pattern": "version:\\s*['\"]([0-9\\.]+)['\"];",
24    "flags": "g"
25  },
26  "replace": "version: '1.2.0';",
27  "include": ["**/*.js", "**/*.ts"]
28}
29
30// Multiple files with glob patterns
31{
32  "type": "content-replace",
33  "path": "./templates",
34  "find": "{{PROJECT_NAME}}",
35  "replace": "my-awesome-project",
36  "include": ["**/*.html", "**/*.md"],
37  "exclude": ["**/node_modules/**"]
38}

Tips

JSON5 Formatting

Useful Tasks supports JSON5, so you can use comments and trailing commas in your configuration files:

1{
2  // This is a comment
3  "type": "output",
4  "text": "Hello, world!"
5}

'set-var' vs 'env-var'

• set-var stores the variable in the task context
• env-var stores the variable in the environment variables

Variable Replacement

Use set-var or env-var to define variables, then reference them in later tasks using ${varName}:

1{
2  "tasks": [
3    { "type": "set-var", "key": "msg", "value": "Hello" },
4    { "type": "env-var", "key": "msg2", "value": "Hello2" },
5    { "type": "output", "text": "The message: ${msg} ${msg2}" }
6  ]
7}

Useful Tasks supports variable replacement using the pattern ${variable.path}:

• Regex: (?<!\\\\)\\$\\{([a-zA-Z0-9\\.\\-_]*)\\}
• Escaping: Use \\${variable.path} to prevent replacement

Built-in Variables

• ${__env.cwd_startup}: The directory where Useful Tasks was launched
• ${__env.cwd_base}: The base working directory (set via --cwd)

Glob Filters

Many tasks support glob patterns for file matching using include and exclude properties:

1{
2  "type": "fs-copy",
3  "src": "./source",
4  "dest": "./destination",
5  "include": ["**/*.js", "**/*.ts"],
6  "exclude": ["**/*.test.js"]
7}

Tasks that support glob filters: set-var, env-var, fs-copy, fs-del, and content-replace.

Advanced Examples

• Use glob patterns in include/exclude fields to match files
• Use regular expressions for advanced content replacement
• Chain multiple configs using sub-tasks

License

This project is licensed under the MIT License. See LICENSE for details.

---

For bugs, questions, or contributions, please visit the GitHub repository.