Hooks
Hooks are cross-cutting interceptors that run before, after, or on error of any command — including commands from other packages. They are defined at the package level alongside profiles in the .aux4 file.
Defining Hooks
Hooks live in the hooks array at the root of the .aux4 file:
1{
2 "profiles": [
3 {
4 "name": "main",
5 "commands": [
6 {
7 "name": "deploy",
8 "execute": [
9 "log:deploying to ${env}"
10 ],
11 "help": {
12 "text": "deploy to environment",
13 "variables": [
14 {
15 "name": "env",
16 "text": "target environment"
17 }
18 ]
19 }
20 }
21 ]
22 }
23 ],
24 "hooks": [
25 {
26 "command": "main/deploy",
27 "before": [
28 "log:preparing deployment to ${env}..."
29 ],
30 "after": [
31 "log:deployment complete: ${__response}"
32 ],
33 "error": [
34 "log:deployment failed: ${__error}"
35 ]
36 }
37 ]
38}1> aux4 deploy --env production1preparing deployment to production...
2deploying to production
3deployment complete: deploying to productionHook Phases
| Phase | When it runs | On failure |
|---|---|---|
| before | Before the command executes | Aborts command, runs error hooks |
| after | After the command succeeds | Logs warning, original exit code preserved |
| error | After the command fails | Logs warning, original error propagates |
Hook steps use the same executors as execute arrays — log:, set:, aux4:, shell commands, etc.
Command Patterns
Hooks match commands by pattern. Use * as a wildcard for any single segment:
| Pattern | Matches |
|---|---|
| main/deploy | Exact profile and command |
| */deploy | Command deploy in any profile |
| deploy/* | Any command in the deploy profile |
| */* | All commands |
Variables in Hooks
Hook steps have access to all variables passed to the intercepted command. These built-in variables are also available:
| Variable | Phases | Description |
|---|---|---|
| ${__command} | all | Full command path |
| ${__scope} | all | Package scope |
| ${__package} | all | Package name |
| ${__response} | after, error | stdout from the command |
| ${__error} | error | Error message |
| ${__exitCode} | after, error | Exit code |
Variable Injection
A set: in a before hook injects variables into the command's scope. The variable is then available in the command and in after/error hooks:
1{
2 "hooks": [
3 {
4 "command": "main/deploy",
5 "before": [
6 "set:timestamp=!date +%s"
7 ],
8 "after": [
9 "log:deployed at ${timestamp}"
10 ]
11 }
12 ]
13}Hook Ordering
Hooks have an optional order field (default 0). Lower values run first. Hooks with the same order run by package installation order:
1{
2 "hooks": [
3 {
4 "command": "main/deploy",
5 "order": 10,
6 "before": ["log:second"]
7 },
8 {
9 "command": "main/deploy",
10 "order": 5,
11 "before": ["log:first"]
12 }
13 ]
14}Conditional Hooks (params)
Hooks can match based on variable values using the params field. All specified params must match (AND). Use | for alternatives (OR):
1{
2 "hooks": [
3 {
4 "command": "main/deploy",
5 "params": {
6 "env": "production"
7 },
8 "before": [
9 "confirm:Are you sure you want to deploy to production?"
10 ]
11 },
12 {
13 "command": "main/deploy",
14 "params": {
15 "env": "dev|staging"
16 },
17 "before": [
18 "log:deploying to non-prod ${env}"
19 ]
20 }
21 ]
22}When --env production is passed, only the first hook fires. When --env dev or --env staging, only the second. Hooks without params always match.
Skipping Hooks
Use the --noHooks flag or AUX4_NO_HOOKS=true environment variable:
1> aux4 deploy --env production --noHooks
2> AUX4_NO_HOOKS=true aux4 deploy --env productionA command can also block hooks by setting noHooks in its definition:
1{
2 "name": "internal-task",
3 "execute": ["echo secret"],
4 "noHooks": true
5}Blocked Executors
The profile: and stdin: executors cannot be used in hooks and will produce an error. Hooks also do not trigger other hooks — there is no recursion.
Hook Discovery
1> aux4 aux4 hooks # list all hooks
2> aux4 aux4 hooks --command "main/deploy" # filter by command
3> aux4 aux4 hooks --package mycompany/deploy-hooks # filter by package
4> aux4 deploy --showHooks # show hooks for a command