README.md 3.47 KB
Newer Older
1 2
# Rocket.Chat Apps CLI
The Rocket.Chat Apps CLI for interacting with Apps.
3

4
## Getting Started
Bradley Hilton's avatar
Bradley Hilton committed
5
Extremely simple.
6

7
```
8
npm install -g @rocket.chat/apps-cli
9
```
10

11
## Rocket.Chat App Development
12

13
### Logging Inside an App
14 15
Due to limitations of NodeJS's `vm` package we have had to implement a custom logger class.
To make usage of this you can use `this.getLogger()` and then do the normal `console` style logging.
16

17
### `rc-apps create`
18

19
The development tools provide a command to quickly scaffold a new Rocket.Chat App, simply run `rc-apps create` and a new folder will be created inside the current working directory with a basic App which does nothing but will compile and be packaged in the `dist` folder.
20 21 22

### App description

23
The app description file, named `app.json`, contains basic information about the app. You can check the [app-schema.json](https://github.com/RocketChat/Rocket.Chat.Apps-engine/blob/master/src/definition/app-schema.json) file for all the detailed information and fields allowed in the app description file, the basic structure is similar to this:
24 25 26 27 28 29 30

```
{
    "id": "5cb9a329-0613-4d39-b20f-cc2cc9175df5",
    "name": "App Name",
    "nameSlug": "app-name",
    "version": "0.0.1",
Douglas Gubert's avatar
1.4.0  
Douglas Gubert committed
31
    "requiredApiVersion": "^1.4.0",
32 33 34 35 36 37 38 39 40 41 42 43
    "description": "App which provides something very useful for Rocket.Chat users.",
    "author": {
        "name": "Author Name <author@email.com>",
        "support": "Support Url or Email"
    },
    "classFile": "main.ts",
    "iconFile": "beautiful-app-icon.jpg"
}
```

### Extending the App class

44
The basic creation of an App is based on extending the `App` class from the Rocket.Chat Apps _definition_ library. Your class also has to implement the constructor and optionally the `initialize` function, for more details on those check the [App definition documentation](https://rocketchat.github.io/Rocket.Chat.Apps-engine/classes/app.html).
45 46 47

```
import {
48
    IAppAccessors,
49 50 51
    IConfigurationExtend,
    IEnvironmentRead,
    ILogger,
52 53 54
} from '@rocket.chat/apps-engine/definition/accessors';
import { App } from '@rocket.chat/apps-engine/definition/App';
import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata';
55 56

export class TodoListApp extends App {
57 58
    constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) {
        super(info, logger, accessors);
59 60 61 62 63 64 65 66 67 68 69
    }

    public async initialize(configurationExtend: IConfigurationExtend, environmentRead: IEnvironmentRead): Promise<void> {
        await this.extendConfiguration(configurationExtend, environmentRead);
        this.getLogger().log('Hello world from my app');
    }
}
```

### Packaging the app

70
Currently the Rocket.Chat servers and Marketplace allow submission of zip files, these files can be created by running `rc-apps package` which packages your app and creates the zip file under `dist` folder.
ritwizsinha's avatar
ritwizsinha committed
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92

### Uploading the app 
For uploading the app you need add to the required parameters in the .rcappsconfig already created in the apps directory. It accepts two types of objects:-

1. Upload using username, password

```
{
    url: string;
    username: string;
    password: string;
}
```
2. Upload using personal access token and userId 

```
{
    url: string;
    userId: string;
    token: string;
}
```
93 94 95

### Enabling autocomplete for commands

Douglas Gubert's avatar
1.7.0  
Douglas Gubert committed
96
To enable autocomplete for the apps cli use the command `rc-apps autocomplete <your-shell-type>` with the shell type as zsh or bash as the supported types. This would provide a step by step instruction to enable shell completion in your preferred shell.