1# CLI Scripting with Roc
 2
 3Scripts run with `roc` or compile to standalone binaries via the basic-cli platform.
 4
 5**Platform version**: Examples use basic-cli 0.20.0. Check https://github.com/roc-lang/basic-cli/releases for latest.
 6
 7## Script structure
 8
 9```roc
10#!/usr/bin/env roc
11app [main!] { cli: platform "https://github.com/roc-lang/basic-cli/releases/download/0.20.0/X73hGh05nNTkDHU06FHC0YfFaQB1pimX7gncRcao5mU.tar.br" }
12
13import cli.Stdout
14
15main! = |_args|
16    Stdout.line!("Hello, World!")
17```
18
19Make executable: `chmod +x script.roc`, then run: `./script.roc`
20
21If `roc` not in PATH, use full path in shebang: `#!/home/user/.local/share/roc/current/roc`
22
23## Command-line arguments
24
25```roc
26#!/usr/bin/env roc
27app [main!] {
28    cli: platform "https://github.com/roc-lang/basic-cli/releases/download/0.20.0/X73hGh05nNTkDHU06FHC0YfFaQB1pimX7gncRcao5mU.tar.br",
29}
30
31import cli.Stdout
32import cli.Arg exposing [Arg]
33
34main! : List Arg => Result {} _
35main! = |raw_args|
36    args = List.map(raw_args, Arg.display)
37
38    # Index 0 is executable path, 1 is first real argument
39    when List.get(args, 1) is
40        Err(_) ->
41            Err(Exit(1, "Error: Expected one argument\n\tUsage: ./script.roc <input>"))
42
43        Ok(first_arg) ->
44            Stdout.line!("Received: ${first_arg}")
45```
46
47## Platform imports
48
49Common modules from `cli` platform:
50
51| Module | Purpose |
52|--------|---------|
53| `cli.Stdout` | Write to stdout |
54| `cli.Stdin` | Read from stdin |
55| `cli.File` | File operations |
56| `cli.Path` | Path handling |
57| `cli.Arg` | Command-line arguments |
58| `cli.Env` | Environment variables |
59| `cli.Dir` | Directory operations |
60
61## Reading stdin
62
63```roc
64import cli.Stdin
65import cli.Stdout
66
67main! = |_args|
68    input = Stdin.line!
69    Stdout.line!("You entered: ${input}")
70```
71
72## File operations
73
74```roc
75import cli.File
76import cli.Path
77import cli.Stdout
78
79main! = |_args|
80    path = Path.from_str("input.txt")
81    content = File.read_utf8!(path)?
82    Stdout.line!("File content: ${content}")
83```
84
85## When to use Roc scripts
86
87**Good for:**
88- Type-safe scripts catching errors at compile time
89- Functional programming enthusiasts
90- Long-lived scripts benefiting from stability
91- Learning functional programming
92
93**Avoid for:**
94- Production-critical code (Roc pre-1.0, breaking changes possible)
95- Quick throwaway scripts (compilation overhead)
96- When team doesn't know functional programming