browser_cli 1.0.0-alpha.2

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';


  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() {
    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.

Changelog #

0.0.1 #

  • Initial version, created by Stagehand

0.1.0 #

  • Initial upload. Framework is partially in place.

1.0.0-alpha #

  • Basic command line functionality in place (minus file system).
  • Interactive IO.
  • Process management.
  • Environment variable storage and recall.
  • Command completion.
  • Input history.
  • Standard library processes thus far:
    • authentication (pseudo for now)
    • echo
    • export
    • help
    • jobs
    • printenv
    • testinput
    • unset

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  browser_cli: ^1.0.0-alpha.2

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:browser_cli/command_line_interface.dart';
import 'package:browser_cli/environment_variables.dart';
import 'package:browser_cli/file_manager.dart';
import 'package:browser_cli/process_library.dart';
import 'package:browser_cli/process_manager.dart';
import 'package:browser_cli/utils.dart';
Awaiting analysis to complete.