@@ -12,16 +12,19 @@ This guide covers how to set up and work with the Flarum CLI codebase locally.
12121 . ** Clone the repository** (if you haven't already)
1313
14142 . ** Install dependencies:**
15+
1516 ``` bash
1617 yarn install
1718 ```
1819
19203 . ** Build the TypeScript source:**
21+
2022 ``` bash
2123 yarn prepack
2224 ```
2325
2426 This command:
27+
2528 - Compiles TypeScript from ` src/ ` to ` lib/ `
2629 - Generates the oclif manifest
2730 - Updates the README with command documentation
@@ -31,48 +34,57 @@ This guide covers how to set up and work with the Flarum CLI codebase locally.
3134You have several options for running the CLI during development:
3235
3336### Option 1: Direct execution via bin/run
37+
3438``` bash
3539./bin/run [command]
3640```
3741
3842Example:
43+
3944``` bash
4045./bin/run --help
4146./bin/run init
4247./bin/run make model
4348```
4449
4550### Option 2: Create a development alias (recommended)
51+
4652Add an alias to your shell configuration file without affecting existing installations:
4753
4854** For zsh** (add to ` ~/.zshrc ` ):
55+
4956``` bash
5057alias fl-dev=' /path/to/cli/bin/run'
5158```
5259
5360** For bash** (add to ` ~/.bashrc ` or ` ~/.bash_profile ` ):
61+
5462``` bash
5563alias fl-dev=' /path/to/cli/bin/run'
5664```
5765
5866After adding the alias, reload your shell:
67+
5968``` bash
6069source ~ /.zshrc # or source ~/.bashrc
6170```
6271
6372Then use:
73+
6474``` bash
6575fl-dev [command]
6676```
6777
6878This allows you to keep your existing ` fl1 ` , ` fl2 ` , etc. aliases intact while having a dedicated ` fl-dev ` for local development.
6979
7080### Option 3: Link globally for development
81+
7182``` bash
7283yarn link
7384```
7485
7586After linking, you can use any of these commands:
87+
7688- ` flarum-cli [command] `
7789- ` fl [command] `
7890- ` fl2 [command] `
@@ -96,11 +108,13 @@ After linking, you can use any of these commands:
96108### Testing
97109
98110Run the test suite:
111+
99112``` bash
100113yarn test
101114```
102115
103116This will:
117+
104118- Run Jest tests
105119- Check code formatting with Prettier
106120- Lint code with ESLint
@@ -109,6 +123,7 @@ This will:
109123### Code Formatting
110124
111125Format code automatically:
126+
112127``` bash
113128yarn format
114129```
@@ -146,36 +161,43 @@ This runs ESLint with auto-fix and Prettier.
146161### Key Concepts
147162
148163** Commands** (in ` src/commands/ ` )
164+
149165- User-facing CLI commands
150166- Built on oclif framework
151167- Orchestrate step execution
152168
153169** Steps** (in ` src/steps/ ` )
170+
154171- Granular, reusable operations
155172- Modify in-memory filesystem
156173- Can be composed atomically
157174- Support parameter sharing between steps
158175
159176** Step Manager**
177+
160178- Fluent API for chaining steps
161179- Handles optional steps
162180- Manages parameter passing between steps
163181- Supports atomic groups for transactional changes
164182
165183** Scaffolding System** (` src/boilersmith/ ` )
184+
166185- Manages extension infrastructure modules
167186- Supports initialization and updates
168187- Module-based file and config ownership
169188
170189## Debugging
171190
172191### Running with Node Inspector
192+
173193``` bash
174194node --inspect ./bin/run [command]
175195```
176196
177197### Verbose Output
198+
178199Most commands support flags for additional output. Check command help:
200+
179201``` bash
180202./bin/run [command] --help
181203```
@@ -206,14 +228,17 @@ Most commands support flags for additional output. Check command help:
206228## Troubleshooting
207229
208230### "Command not found" after changes
231+
209232- Ensure you've run ` yarn prepack ` to rebuild
210233- Check that ` lib/ ` directory exists and contains compiled code
211234
212235### TypeScript errors
236+
213237- Run ` yarn posttest ` to see type checking output
214238- Ensure ` tsconfig.json ` includes your new files
215239
216240### Tests failing
241+
217242- Run ` yarn test ` to see full output
218243- Check that step unit tests match your changes
219244
0 commit comments