Flarum CLI v1.0

SychO

Flarum CLI

A CLI for developing Flarum extensions.

📣 The Announcement

Supporting our extension ecosystem in building even more awesome extensions, is something we firmly believe in. As such @askvortsov has been hammering away at this project (RFC: Flarum CLI Alpha, Flarum CLI Dev Diary), setting up a solid foundation for it to create a powerful tool for extension development that would help developers by automating some repetitive and menial tasks, and allow them to get into the actual work without much hassle.

Today, we're very excited to announce the 1.0 version of this tool, it comes with a range of commands to assist you along the way.

📥 Installation

Using npm simply run the following command to install the CLI globally.

If you have the alpha version installed, remove it first:

$ npm uninstall -g flarum-cli

Now install the new package:

$ npm install -g @flarum/cli

To run a command, use either flarum-cli or fl:

$ flarum-cli COMMAND
$ fl COMMAND

To see a list of available commands, run either of:

$ flarum-cli
$ flarum-cli --help

⬆️ Updating

$ npm update -g @flarum/cli

🌟 Highlights

The CLI has different types of commands for different tasks:

Initialisation

flarum-cli init [PATH]: Generates a blank extension skeleton, including all recommended infrastructure.

Infrastructure

flarum-cli infra backend-testing [PATH]: Adds (or updates) infrastructure for running automated backend tests.

Backend Boilerplate Generation: Generates different types of backend classes and/or extenders, ready to be used.

flarum-cli make backend api-controller [PATH]
flarum-cli make backend api-serializer [PATH]
flarum-cli make backend api-serializer-attributes [PATH]
flarum-cli make backend command [PATH]
flarum-cli make backend event-listener [PATH]
flarum-cli make backend handler [PATH]
flarum-cli make backend integration-test [PATH]
flarum-cli make backend job [PATH]
flarum-cli make backend migration [PATH]
flarum-cli make backend model [PATH]
flarum-cli make backend policy [PATH]
flarum-cli make backend repository [PATH]
flarum-cli make backend route [PATH]
flarum-cli make backend service-provider [PATH]
flarum-cli make backend validator [PATH]

Frontend Boilerplate Generation: Generate frontend components/classes, ready to be used.

flarum-cli make frontend component [PATH]
flarum-cli make frontend modal [PATH]
flarum-cli make frontend model [PATH]

Code Updates:

flarum-cli update js-imports [PATH]: Adds admin/forum/common namespaces to all JS imports from flarum core.

And of course, you can always use the help command to see a list of all available commands with their descriptions:

flarum-cli help [COMMAND]

🔥 The Most Powerful Commands

Of all the aforementioned commands, the two most powerful ones that will make a huge difference, are the extension initialisation command and the backend model generation command. The former obviously allows to kickstart the extension with the recommended skeleton from the Core Dev team, while the latter not only creates the backend model, it allows to create all the classes related to the model, from just its name:

Table migration
Policy
API Serializer
CRUD API Controllers
CRUD Handlers
Repository
Validator
Routes
Related Extenders

terminal_example
example_project_with_model_command

🧑‍🏭 Support & Feedback

If you encounter any problems while using the CLI, or would like to propose additional features/commands, please open an issue in the github repository.

Any and all feedback is appreciated.

Links

GitHub
npm

stimw

Congratulations!

iPurpl3x

flarum-cli update js-imports, that one is REALLY time saving !

Great job guys 🥳 !

EvilExecutor

Hi, I installed the flarum-cli everything works fine when I run flarum-cli COMMAND but fl COMMAND doesn't do anything...

(I don't have much experience with node or npm so maybe I've done something wrong 🤔 )

SychO

EvilExecutor could be a windows specific issue

clarkwinkelmann

EvilExecutor I have not tried the client on Windows yet, but there is the where Windows command to locate an executable. Using where fl you could verify which program Windows is running with the fl command. Maybe you have another app that uses that short name.

On my Windows VM without NPM running fl says "'fl' is not recognized as an internal or external command, operable program or batch file" so at least it doesn't look to be a default Windows app.

EvilExecutor

SychO Do you think it is a configuration or installation fault? Or could it be a windows specific bug, if that's the shall I create an issue at the github repo?

SychO

EvilExecutor I'm only guessing windows specific because I haven't used the CLI there yet, but I can't tell until I look into it, feel free to create an issue on the repo so that it doesn't get lost.

EvilExecutor

Justoverclock Thanks for the response, so most probably I've done something wrong from my end.

SychO feel free to create an issue on the repo so that it doesn't get lost.

Done.

Justoverclock

on windows works fine for me, if this can help...

FBioCS1

I got some error when executing npm install -g @flarum/cli

npm ERR! code ENOLOCK
npm ERR! audit This command requires an existing lockfile.
npm ERR! audit Try creating one first with: npm i --package-lock-only
npm ERR! audit Original error: loadVirtual requires existing shrinkwrap file

full log is here

0 verbose cli [ '/usr/bin/node', '/usr/local/bin/npm', 'audit' ]
1 info using npm@7.20.5
2 info using node@v10.24.0
3 timing npm:load:whichnode Completed in 1ms
4 timing config:load:defaults Completed in 1ms
5 timing config:load:file:/usr/local/lib/node_modules/npm/npmrc Completed in 3ms
6 timing config:load:builtin Completed in 3ms
7 timing config:load:cli Completed in 2ms
8 timing config:load:env Completed in 0ms
9 timing config:load:project Completed in 1ms
10 timing config:load:file:/root/.npmrc Completed in 0ms
11 timing config:load:user Completed in 0ms
12 timing config:load:file:/etc/npmrc Completed in 0ms
13 timing config:load:global Completed in 0ms
14 timing config:load:validate Completed in 0ms
15 timing config:load:credentials Completed in 2ms
16 timing config:load:setEnvs Completed in 1ms
17 timing config:load Completed in 10ms
18 timing npm:load:configload Completed in 10ms
19 timing npm:load:setTitle Completed in 0ms
20 timing npm:load:setupLog Completed in 0ms
21 timing config:load:flatten Completed in 2ms
22 timing npm:load:cleanupLog Completed in 3ms
23 timing npm:load:configScope Completed in 0ms
24 timing npm:load:projectScope Completed in 1ms
25 timing npm:load Completed in 19ms
26 timing arborist:ctor Completed in 1ms
27 timing command:audit Completed in 5ms
28 verbose stack Error: loadVirtual requires existing shrinkwrap file
28 verbose stack     at Arborist.loadVirtual (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/load-virtual.js:57:18)
29 verbose cwd /root
30 verbose Linux 4.19.0-10-amd64
31 verbose argv "/usr/bin/node" "/usr/local/bin/npm" "audit"
32 verbose node v10.24.0
33 verbose npm  v7.20.5
34 error code ENOLOCK
35 error audit This command requires an existing lockfile.
36 error audit Try creating one first with: npm i --package-lock-only
37 error audit Original error: loadVirtual requires existing shrinkwrap file
38 verbose exit 1

SychO

FBioCS1 from that log it sounds like you're running npm audit instead, are you sure it failed when installing ? did you try running flarum-cli --help ?

FBioCS1

SychO the Flarum CLI is install successfully, but errors occurred while installing, it shows

npm WARN EBADENGINE Unsupported engine { package: 'mem-fs@2.2.1',
npm WARN EBADENGINE   required: { node: '>=12' },
npm WARN EBADENGINE   current: { node: 'v10.24.0', npm: '7.20.5' } }
npm WARN EBADENGINE Unsupported engine { package: 'mem-fs-editor@8.1.2',
npm WARN EBADENGINE   required: { node: '>=12.10.0' },
npm WARN EBADENGINE   current: { node: 'v10.24.0', npm: '7.20.5' } }

changed 367 packages, and audited 368 packages in 44s

27 packages are looking for funding
  run `npm fund` for details

2 high severity vulnerabilities

Some issues need review, and may require choosing
a different dependency.

**Run `npm audit` for details.**

and i ran npm audit for details, then i got this full error log:

0 verbose cli [ '/usr/bin/node', '/usr/local/bin/npm', 'audit' ]
1 info using npm@7.20.5
2 info using node@v10.24.0
3 timing npm:load:whichnode Completed in 1ms
4 timing config:load:defaults Completed in 1ms
5 timing config:load:file:/usr/local/lib/node_modules/npm/npmrc Completed in 3ms
6 timing config:load:builtin Completed in 3ms
7 timing config:load:cli Completed in 2ms
8 timing config:load:env Completed in 0ms
9 timing config:load:project Completed in 1ms
10 timing config:load:file:/root/.npmrc Completed in 0ms
11 timing config:load:user Completed in 0ms
12 timing config:load:file:/etc/npmrc Completed in 0ms
13 timing config:load:global Completed in 0ms
14 timing config:load:validate Completed in 0ms
15 timing config:load:credentials Completed in 2ms
16 timing config:load:setEnvs Completed in 1ms
17 timing config:load Completed in 10ms
18 timing npm:load:configload Completed in 10ms
19 timing npm:load:setTitle Completed in 0ms
20 timing npm:load:setupLog Completed in 0ms
21 timing config:load:flatten Completed in 2ms
22 timing npm:load:cleanupLog Completed in 3ms
23 timing npm:load:configScope Completed in 0ms
24 timing npm:load:projectScope Completed in 1ms
25 timing npm:load Completed in 19ms
26 timing arborist:ctor Completed in 1ms
27 timing command:audit Completed in 5ms
28 verbose stack Error: loadVirtual requires existing shrinkwrap file
28 verbose stack     at Arborist.loadVirtual (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/load-virtual.js:57:18)
29 verbose cwd /root
30 verbose Linux 4.19.0-10-amd64
31 verbose argv "/usr/bin/node" "/usr/local/bin/npm" "audit"
32 verbose node v10.24.0
33 verbose npm  v7.20.5
34 error code ENOLOCK
35 error audit This command requires an existing lockfile.
36 error audit Try creating one first with: npm i --package-lock-only
37 error audit Original error: loadVirtual requires existing shrinkwrap file
38 verbose exit 1

I can run flarum-cli init, and it can generate the skeleton of extension. I just don't know what these errors means and if they have a negative effect on my server.

SychO

FBioCS1 They don't it's fine, you only use the CLI to generate stubs and boilerplate.

EvilExecutor

clarkwinkelmann Hey clark thanks for your reply. When I tried where on my Terminal Emulator (Tabby) it didn't return anything. So I thought something was some problem with Tabby and luckily tried fl [CMD] on
Command Prompt. Then it did respond.

Then I tried running fl [CMD] PowerShell once again there was no response. So I'm guessing it is caused only on PowerShell.

Ralkage

EvilExecutor I can confirm the same issue with PowerShell, no output after simply entering fl 🙂

EvilExecutor

I'm not sure whether this is the correct place to report but in the docs,

https://docs.flarum.org/extend/#useful-resources

Flarum Blank Extension Generator

https://docs.flarum.org/extend/frontend.html#transpilation-and-file-structure

This portion of the guide will explain the necessary file setup for extensions. Once again, we highly recommend using the unofficial FoF extension generator (opens new window)to set up the file structure for you.

These parts should be updated 🙃

010101

Should the extension template's readme include this?

Uninstall

Deactivate, tap the purge button (cleans up the database), then run this composer command:

composer remove zerosonesfun/flarum-bbcode-button:"*"

I think extensions should still include this. At least until Flarum can fully auto uninstall. Note the fact that I mention the purge button.

clarkwinkelmann

010101 PS: correct command would be composer remove zerosonesfun/flarum-bbcode-button

:"*" can only be appended to require. remove and update only take a package name as parameter.