What causes "line %d: 'dep' requires a subcommand (add|remove)" in gastownhall/beads?

Add the subcommand: use `dep add ` or `dep remove ` on that line.

line %d: 'dep' requires a subcommand (add|remove)

Error message

line %d: 'dep' requires a subcommand (add|remove)

What it means

The `dep` batch command is a two-level command requiring a subcommand (`add` or `remove`). If a line starts with `dep` but has no second token, `parseBatchScript` rejects the whole script with this message before any writes occur.

Source

Thrown at cmd/bd/batch.go:276

			return nil, fmt.Errorf("line %d: %w", lineNo, err)
		}
		if len(tokens) == 0 {
			continue
		}
		op := batchOp{line: lineNo, raw: trimmed}
		switch tokens[0] {
		case "close":
			op.cmd = "close"
			op.args = tokens[1:]
		case "update":
			op.cmd = "update"
			op.args = tokens[1:]
		case "create":
			op.cmd = "create"
			op.args = tokens[1:]
		case "dep":
			if len(tokens) < 2 {
				return nil, fmt.Errorf("line %d: 'dep' requires a subcommand (add|remove)", lineNo)
			}
			switch tokens[1] {
			case "add":
				op.cmd = "dep.add"
			case "remove", "rm":
				op.cmd = "dep.remove"
			default:
				return nil, fmt.Errorf("line %d: unknown dep subcommand %q (want add|remove)", lineNo, tokens[1])
			}
			op.args = tokens[2:]
		default:
			return nil, fmt.Errorf("line %d: unsupported batch command %q (supported: close, update, create, dep add, dep remove)", lineNo, tokens[0])
		}
		ops = append(ops, op)
	}
	if err := scanner.Err(); err != nil {
		return nil, err
	}

View on GitHub (pinned to 71377f2769)

Solutions

Add the subcommand: use `dep add <child> <parent>` or `dep remove <child> <parent>` on that line.
If you intended to inspect dependencies, use `bd dep <id>` outside batch mode instead.
Validate with `bd batch --dry-run` before executing.

Example fix

// before (batch file)
dep bd-1 bd-2
// after
dep add bd-1 bd-2

Defensive patterns

Strategy: validation

Validate before calling

# Ensure every 'dep' line has a valid subcommand before running:
awk '$1=="dep" && !(($2=="add")||($2=="remove")||($2=="rm")) { print "bad dep line " NR ": " $0 }' batch.txt

Try / catch

if err := runBdBatch(file); err != nil {
    if strings.Contains(err.Error(), "'dep' requires a subcommand") {
        return fmt.Errorf("script rejected, no writes made: %w", err)
    }
    return err
}

Prevention

Use the full form `dep add <child> <parent>` / `dep remove <child> <parent>` in scripts.
Run dependency queries with `bd dep <id>` outside batch mode.
Lint batch files with `bd batch --dry-run` in CI before applying.

When it happens

Trigger: A batch script line reading just `dep` (e.g. `dep` alone, or `dep` at end of a truncated line) passed to `bd batch`.

Common situations: Truncated lines in generated scripts; users assuming `dep` alone lists dependencies (it does not in batch mode); copy-paste dropping the `add bd-1 bd-2` tail.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/9f68d0c6e1b64748. Report an issue: GitHub.