Add documented public api

packages/angular/cli/README.md

@@ -37,6 +37,7 @@ with NPM 5.5.1 or higher.
 * [Updating Angular CLI](#updating-angular-cli)
 * [Development Hints for working on Angular CLI](#development-hints-for-working-on-angular-cli)
 * [Documentation](#documentation)
+* [Programmatic usage](#programmatic-usage)
 * [License](#license)
 
 ## Installation
@@ -252,6 +253,18 @@ In addition to this one, another, more elaborated way to capture a CPU profile u
 
 The documentation for the Angular CLI is located in this repo's [wiki](https://github.com/angular/angular-cli/wiki).
 
+## Programmatic usage
+
+You can also use angular cli programmatically. Here is an example on how to run `ng test --watch false` from inside your nodejs application:
+
+```js
+import cli from '@angular/cli';
+
+const returnCode = await cli({ args: ['test', '--watch', 'false'] });
+```
+
+Types for typescript are included.
+
 ## License
 
 MIT

packages/angular/cli/lib/cli/index.ts → packages/angular/cli/lib/cli/main.ts

@@ -12,8 +12,24 @@ import { runCommand } from '../../models/command-runner';
 import { getWorkspaceRaw } from '../../utilities/config';
 import { getWorkspaceDetails } from '../../utilities/project';
 
+export interface CliOptions {
+  testing?: boolean;
+  /**
+   * The cli arguments to provide to the command (without the `ng`)
+   */
+  args: string[];
+}
 
-export default async function(options: { testing?: boolean, cliArgs: string[] }) {
+/**
+ * Run an arbitrary `ng` command.
+ *
+ * @example
+ * const returnCode = await cli({ args: ['test', '--watch', 'false' ] } );
+ *
+ * @param options The cli options, including the arguments use to run
+ * @returns {Promise<number>} A promise that resolves to the exit code of the ng command.
+ */
+export default async function(options: CliOptions): Promise<number> {
   const logger = new logging.IndentLogger('cling');
   let loggingSubscription;
   if (!options.testing) {
@@ -34,7 +50,7 @@ export default async function(options: { testing?: boolean, cliArgs: string[] })
   }
 
   try {
-    const maybeExitCode = await runCommand(options.cliArgs, logger, projectDetails);
+    const maybeExitCode = await runCommand(options.args, logger, projectDetails);
     if (typeof maybeExitCode === 'number') {
       console.assert(Number.isInteger(maybeExitCode));
 

packages/angular/cli/lib/init.ts

@@ -126,7 +126,7 @@ try {
   // library from a package.json. Instead, include it from a relative
   // path to this script file (which is likely a globally installed
   // npm package). Most common cause for hitting this is `ng new`
-  cli = require('./cli');
+  cli = require('./cli/main');
 }
 
 if ('default' in cli) {
@@ -144,7 +144,7 @@ try {
 }
 
 cli({
-  cliArgs: process.argv.slice(2),
+  args: process.argv.slice(2),
   inputStream: standardInput,
   outputStream: process.stdout,
 })

packages/angular/cli/package.json

@@ -2,7 +2,7 @@
   "name": "@angular/cli",
   "version": "0.0.0",
   "description": "CLI tool for Angular",
-  "main": "lib/cli/index.js",
+  "main": "lib/cli/main.js",
   "trackingCode": "UA-8594346-19",
   "bin": {
     "ng": "./bin/ng"

scripts/create.ts

@@ -7,7 +7,7 @@
  */
 // tslint:disable:no-implicit-dependencies
 import { logging } from '@angular-devkit/core';
-import cli from '@angular/cli/lib/cli';
+import cli from '@angular/cli';
 import * as child_process from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -20,7 +20,7 @@ export interface CreateOptions {
 
 async function _ng(command: string, ...args: string[]) {
   const exitCode = await cli({
-    cliArgs: [command, ...args],
+    args: [command, ...args],
   });
 
   if (exitCode !== 0) {