browser_cli

This dart package is a Command Line Interface for the web browser. Pull it into your website and create some custom processes to have all the sweet command line goodness at your fingertips!

Getting Started

Add code to html page

The following goes inside the <head>:

<script defer src="main.dart" type="application/dart"></script>
<script defer src="packages/browser/dart.js"></script>

In the <body>, where you want the shell located, add the following:

<div id="cli-shell"></div>

Create or import processes

Any process that you want to run in the CLI needs to extend the Process class, and it needs to also have a factory that extends the ProcessFactory class.

ProcessFactory Example:

A ProcessFactory should follow the model below, providing a COMMAND, USAGE, SHORT_DESCRIPTION, and LONG_DESCRIPTION.

class EchoProcessFactory extends ProcessFactory {
  static final String COMMAND = 'echo';
  static final String USAGE = 'USAGE: echo <string>';
  static final String SHORT_DESCRIPTION =
      'Prints the supplied input back to the shell.';
  static final String LONG_DESCRIPTION =
      'Prints the supplied input back to the shell';

  EchoProcessFactory()
      : super(COMMAND, USAGE, SHORT_DESCRIPTION, LONG_DESCRIPTION);

  EchoProcess createProcess(int id, List args) =>
      new EchoProcess(id, COMMAND, args, this);
}

Process Example:

The only two required API for a Process are the constructor and the start() method. Below is a very basic Process, but they can be much more complex. Check out other Processes in the standard library for examples of different ways to parse the arguments, how to request user input within a running process, how to start other processes from within a process, and more!

class EchoProcess extends Process {
  EchoProcess(int id, String command, List args, ProcessFactory factory)
      : super(id, command, args, factory);

  Future start() async {
    if (args.isNotEmpty) {
      await output(new DivElement()..text = args.join(' '));
    } else {
      await output(new DivElement()..innerHtml = nonBreakingLineSpace);
    }
  }
}

Create a main.dart and register desired process factories

Make sure to register all the standard library process factories, as well as any custom process factories you may have.

import 'package:browser_cli/command_line_interface.dart';
import 'package:browser_cli/process_library.dart';
import 'package:my_cool_project/process_library.dart';

CommandLineInterface interface;

void main() {
  interface = new CommandLineInterface();
  _registerProcesses();
}

_registerProcesses() {
  interface.processManager.registerProcessFactories([
    new EchoProcessFactory(),
    new ExportProcessFactory(),
    new HelpProcessFactory(),
    new JobsProcessFactory(),
    new PrintEnvProcessFactory(),
    new UnsetProcessFactory(),
    // ...
  ]);
}

Style your CLI

You can use the default stylings provided with the package, or you can make your own! Below are some (but not all) of the id and class names used by browser_cli. To get a more complete list, check out the utils library.

id

  • cli-shell - The container for the CLI shell.
  • cli-standard-input - The div the user types in.
  • cli-prompt - The leading bit of text in the standard input div. Defaults to "~ user$"

  • cli-last-output - The last div output to the shell.

class

  • cli-output - This class applies to all output divs.
  • cli-stderr - This class is added to an output div when it's displaying an error message.

  • cli-input - This class applies to all (current and previous) input divs.

  • cli-visible-scroll - When you want a scrollbar in an output div.
  • cli-bordered-scroll-area - When you want the scroll area to have a border.

  • cli-hidden - When you want something to be hidden.

Libraries

command_line_interface

This library provides the main interface between the user and the application. It receives input from the user, parses input, displays output to the user, and deals with other elements of user interaction.

environment_variables

This library provides functionality for dealing with environment variables available to the user and across processes in the application.

file_manager
process

This library provides all the concrete Process and ProcessFactory classes that come standard with browser_cli. It also provides a good resource to look at when designing your own custom Process.

process_manager

This library contains the ProcessManager class, as well as the abstract Process and ProcessFactory classes. It handles things like starting and stopping processes, piping input and output to and from the CommandLineInterface, handling asynchronous and synchronous completion, differentiating between background and foreground processes, and more.

utils

This library provides utility functions and variables for browser_cli that can be easily shared across other libraries.