@servicestack/cli/README.md

Simple CLI utils for ServiceStack projects

# @servicestack/cli

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/servicestack-heart-typescript.png)](http://docs.servicestack.net/typescript-add-servicestack-reference)

## Simple command-line utilities for ServiceStack

The `@servicestack/cli` provides simple command-line utilities to easily Add and Update ServiceStack References for all of ServiceStack's supported languages:

### Supported Languages

* [C# Add ServiceStack Reference](http://docs.servicestack.net/csharp-add-servicestack-reference)
* [TypeScript Add ServiceStack Reference](http://docs.servicestack.net/typescript-add-servicestack-reference)
* [Swift Add ServiceStack Reference](http://docs.servicestack.net/swift-add-servicestack-reference)
* [Java Add ServiceStack Reference](http://docs.servicestack.net/java-add-servicestack-reference)
* [Kotlin Add ServiceStack Reference](http://docs.servicestack.net/kotlin-add-servicestack-reference)
* [VB.NET Add ServiceStack Reference](http://docs.servicestack.net/vbnet-add-servicestack-reference)
* [F# Add ServiceStack Reference](http://docs.servicestack.net/fsharp-add-servicestack-reference)

## Installation

Prerequisites: Node.js (>=4.x, 6.x preferred), npm version 3+.

    $ npm install -g @servicestack/cli

This will make the following utilities availble from your command-line which will let you download the Server DTO classes for a remote ServiceStack endpoint in your chosen language which you can use with ServiceStack's generic Service clients to be able to make end-to-end API calls.

| Script | Alias | Language |
| ------ | ----- | -------- |
| csharp-ref | cs-ref | C# |
| typescript-ref | ts-ref | TypeScript |
| typescriptd-ref | tsd-ref | TypeScript Declarations |
| swift-ref | | Swift |
| java-ref | | Java |
| kotlin-ref | kt-ref | Kotlin |
| vbnet-ref | vb-ref | VB.NET |
| fsharp-ref | fs-ref | F# |

## Usage

We'll walkthrough an example using TypeScript to download Server Types from the [techstacks.io](http://techstacks.io) ServiceStack Website to see how this works:

### Adding a ServiceStack Reference

To Add a TypeScript ServiceStack Reference just call `typescript-ref` with the URL of 
a remote ServiceStack instance:

    $ typescript-ref http://techstacks.io

Result:

    Saved to: techstacks.dtos.ts

Calling `typescript-ref` with just a URL will save the DTOs using the Host name, you can override this by specifying a FileName as the 2nd argument:

    $ typescript-ref http://techstacks.io Tech

Result:

    Saved to: Tech.dtos.ts

### Updating a ServiceStack Reference

To Update an existing ServiceStack Reference, call `typescript-ref` with the Filename:

    $ typescript-ref techstacks.dtos.ts

Result:

    Updated: techstacks.dtos.ts

Which will update the File with the latest TypeScript Server DTOs from [techstacks.io](http://techstacks.io). You can also customize how DTOs are generated by uncommenting the [TypeScript DTO Customization Options](http://docs.servicestack.net/typescript-add-servicestack-reference#dto-customization-options) and updating them again.

#### Updating all TypeScript DTOs

Calling `typescript-ref` without any arguments will update all TypeScript DTOs in the current directory:

    $ typescript-ref

Result:

    Updated: Tech.dtos.ts
    Updated: techstacks.dtos.ts

To make it more wrist-friendly you can also use the shorter `ts-ref` alias instead of `typescript-ref`.

### Installing Generic Service Client

Now we have our TechStacks Server DTOs we can use them with the generic `JsonServiceClient` in the [@servicestack/client](https://www.npmjs.com/package/@servicestack/client) npm package to make Typed API Calls.

#### Install @servicestack/client

    $ npm install @servicestack/client

#### TechStacks Example

Once installed create a `demo.ts` file with the example below using both the `JsonServiceClient` from the **@servicestack/client** npm package and the Server DTOs we want to use from our local `techstacks.dtos.ts` above:

```ts
import { JsonServiceClient } from '@servicestack/client';
import { GetTechnology, GetTechnologyResponse } from './techstacks.dtos';

var client = new JsonServiceClient("http://techstacks.io")

let request = new GetTechnology()
request.Slug = "ServiceStack"

client.get(request)
    .then(r => console.log(r.Technology.VendorUrl))
```

The `JsonServiceClient` is populated with the **BaseUrl** of the remote ServiceStack instance we wish to call. Once initialized we can send populated Request DTOs and handle
the Typed Response DTOs in Promise callbacks.

To run our TypeScript example we just need to compile it with TypeScript:

    $ tsc demo.ts

Which will generate the compiled `demo.js` (and `typescript.dtos.js`) which we can then run with node:

    $ node demo.js

Result:

    https://servicestack.net

#### Enabling TypeScript async/await 

To make API requests using TypeScript's async/await feature we'll need to create a TypeScript `tsconfig.json` config file that imports ES6 promises and W3C fetch definitions with:

```json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "lib": [ "es2015", "dom" ]
  }
}
```

Now we can create a new `await-demo.ts` file and start using TypeScript's async/await feature which as it can only be called within an `async` function, we'll need to wrap in an async function:

```ts
import { JsonServiceClient } from '@servicestack/client';
import { GetTechnology, GetTechnologyResponse } from './techstacks.dtos';

var client = new JsonServiceClient("http://techstacks.io")

async function main() {
    let request = new GetTechnology()
    request.Slug = "ServiceStack"

    const response = await client.get(request)
    console.log(response.Technology.VendorUrl)
}

main()
```

Now that we have a `tsconfig.json` we can just call `tsc` to compile all our TypeScript source files in our folder:

    $ tsc

And then run the compiled `await-demo.js` with node:

    $ node await-demo.js

Result:

    https://servicestack.net