Skip to content

Commit 879bbd5

Browse files
jayzhangMuyangAmigo
jayzhang
and
MuyangAmigo
authored
docs: link cli user manual doc to official doc site (#10368)
* docs: link cli user manual doc to official doc site * docs: update CLI README and user manual --------- Co-authored-by: Junjie Li <[email protected]>
1 parent fa6f99f commit 879bbd5

File tree

2 files changed

+34
-353
lines changed

2 files changed

+34
-353
lines changed

‎docs/cli/user-manual.md

+14-335
Original file line numberDiff line numberDiff line change
@@ -1,341 +1,20 @@
1-
# teamsapp Command Line Interface
1+
# Teams Toolkit Command Line Interface User Manual
22

3-
teamsapp CLI is a text-based command line interface that accelerates Teams application development. It aims you to provide keyboard-centric experience when building Teams applications. It also enables CI/CD scenario where CLI can be easily integrated in scripts for automation.
3+
Teams Toolkit CLI is a text-based command line interface that accelerates Teams application development. It aims you to provide keyboard-centric experience when building Teams applications. It also enables CI/CD scenario where CLI can be easily integrated in scripts for automation.
44

5-
* [Source code](https://github.com/OfficeDev/teamsapp/tree/dev/packages/cli)
6-
* [Package (NPM)](https://www.npmjs.com/package/@microsoft/teamsapp-cli)
7-
8-
## Get Started
9-
10-
Let's start by installing `teamsapp-cli` from `npm` and run `teamsapp -h` to check all available commands:
11-
12-
```bash
13-
npm install -g @microsoft/teamsapp-cli
14-
teamsapp -h
15-
```
16-
17-
## Supported Commands
18-
19-
| `teamsapp` Commands | Descriptions |
20-
|:---------------- |:-------------|
21-
|`teamsapp add` | Add feature to your Microsoft Teams application. |
22-
|`teamsapp auth` | Manage Microsoft 365 and Azure accounts. |
23-
|`teamsapp collaborator` | Check, grant and list permissions for who can access and manage Microsoft Teams application and Microsoft Entra application. |
24-
|`teamsapp deploy [options]` | Run the deploy stage in teamsapp.yml or teamsapp.local.yml.|
25-
|`teamsapp doctor [options]` | Prerequiste checker for building Microsoft Teams apps. |
26-
|`teamsapp entra-app` | Manage the Microsoft Entra app in the current application.|
27-
|`teamsapp env` | Manage environments.|
28-
|`teamsapp help` | Show Microsoft Teams Toolkit CLI help.|
29-
|`teamsapp install` | Sideload a given application package across Microsoft 365.|
30-
|`teamsapp launchinfo` | Get launch information of an acquired M365 App.|
31-
|`teamsapp list` | List available Microsoft Teams application templates and samples.|
32-
|`teamsapp new` | Create a new Microsoft Teams application.|
33-
|`teamsapp package` | Build your Microsoft Teams app into a package for publishing.|
34-
|`teamsapp preview` | Preview the current application.|
35-
|`teamsapp provision` | Run the provision stage in teamsapp.yml or teamsapp.local.yml.|
36-
|`teamsapp publish` | Run the publish stage in teamsapp.yml.|
37-
|`teamsapp uninstall` | Remove an acquired M365 App.|
38-
|`teamsapp update` | Update the Microsoft Teams App manifest to Teams Developer Portal.|
39-
|`teamsapp upgrade` | Upgrade the project to work with the latest version of Teams Toolkit.|
40-
|`teamsapp validate` | Validate the Microsoft Teams app using manifest schema or validation rules.|
41-
42-
## `teamsapp new`
43-
44-
`teamsapp new` will by default go into interactive mode and guide you through the process of creating a new Teams application by asking few questions. You can also do it in non-interactive mode by setting `--interactive` flag to `false`.
45-
46-
| `teamsapp new` Commands | Descriptions |
47-
|:---------------- |:-------------|
48-
| `teamsapp new sample <sample-id>` | Create an app from an existing sample |
49-
| `teamsapp list samples` | List all the available samples|
50-
51-
### Parameters for `teamsapp new`
52-
53-
| Parameters | Required | Descriptions |
54-
|:---------------- |:-------------|:-------------|
55-
| `capability` | Yes | Specifies the Microsoft Teams App capability. Allowed value: ["bot", "ai-bot", "ai-assistant-bot", etc.]. Use 'teamsfx list templates' to see all available options. |
56-
| `bot-host-type-trigger` | No | Specifies the trigger for `Chat Notification Message` app template. Allowed value: ["http-restify", "http-webapi", "http-and-timer-functions", etc.]. Default value: "http-restify". |
57-
| `spfx-solution` | No | Create a new or import an existing SharePoint Framework solution. Allowed value: ["new", "import"]. Default value: "new". |
58-
| `spfx-install-latest-package` | No | Install the latest version of SharePoint Framework. Default value: true. |
59-
| `spfx-framework-type` | No | Framework. Allowed value: ["react", "minimal", "none"]. Default value: "react". |
60-
| `spfx-webpart-name` | No | Name for SharePoint Framework Web Part. Default value: "helloworld". |
61-
| `spfx-folder` | No | Directory or Path that contains the existing SharePoint Framework solution. |
62-
| `me-architecture` | No | Architecture of Search Based Message Extension. Allowed value: ["new-api", "api-spec", "bot-plugin"]. Default value: "new-api". |
63-
| `openapi-spec-location` | No | OpenAPI description document location. |
64-
| `api-operation` | No | Select Operation(s) Teams Can Interact with. |
65-
| `programming-language` | No | Programming Language Allowed value: ["javascript", "typescript", "csharp"]. Default value: "javascript". |
66-
| `folder` | No | Directory where the project folder will be created in. Default value: "./". |
67-
| `app-name | Yes | Application name. |
68-
69-
### Scenarios for `teamsapp new`
70-
71-
Using interactive mode to create a Teams app is super intuitive, please try it by starting with `teamsapp new`. The following are the few scenerios on controlling all the parameters:
72-
73-
#### Create a new timer triggered notification bot
74-
75-
```bash
76-
teamsapp new -c notification -t timer-functions -l typescript -n myapp -i false
77-
```
78-
79-
#### Import an existing SharePoint Framework solution
80-
81-
```bash
82-
teamsapp new -c tab-spfx -s import --spfx-folder <folder-path> -n myapp -i false
83-
```
84-
85-
## `teamsapp auth`
86-
87-
Manage cloud service accounts. The supported cloud services are `Azure` and `Microsoft 365`.
88-
89-
| `teamsapp auth` Commands | Descriptions |
90-
|:---------------- |:-------------|
91-
| `teamsapp auth list` | Display all connected cloud accounts information. |
92-
| `teamsapp auth login <service>` | Log in to the selected cloud service. |
93-
| `teamsapp auth logout <service>` | log out of selected cloud service. |
94-
95-
## `teamsapp env`
96-
97-
Manage the environments.
98-
99-
| `teamsapp env` Commands | Descriptions |
100-
|:---------------- |:-------------|
101-
| `teamsapp env add <new_env_name> --env <existing_env_name>` | Add a new environment by copying from the specified environment. |
102-
| `teamsapp env list` | List all environments. |
103-
104-
### Scenarios for `teamsapp env`
105-
106-
#### Create a new environment
107-
108-
Add a new environment by copying from the existing dev environment:
109-
110-
```bash
111-
teamsapp env add staging --env dev
112-
```
113-
114-
## `teamsapp provision`
115-
116-
Provision the cloud resources in the current application.
117-
118-
### Parameters for `teamsapp provision`
119-
120-
| Parameters | Required | Descriptions |
121-
|:---------------- |:-------------|:-------------|
122-
|`--env`| Yes| Specifies the environment name for the project scaffolded by Microsoft Teams Toolkit. |
123-
|`--folder`| No | Project folder. Default value: "./". |
124-
125-
## `teamsapp deploy`
126-
127-
This command is used to deploy the current application. By default it will deploy entire project but it's also possible to deploy partially. Options(Multiple) are: `frontend-hosting`, `function`, `apim`, `teamsbot`, `spfx`.
128-
129-
### Parameters for `teamsapp deploy`
130-
131-
| Parameters | Required | Descriptions |
132-
|:---------------- |:-------------|:-------------|
133-
|`--env`| Yes| Specifies the environment name for the project scaffolded by Microsoft Teams Toolkit. |
134-
|`--folder`| No | Project folder. Default value: "./". |
135-
136-
## `teamsapp validate`
137-
138-
Validate current application. This command will validate your application's manifest file.
139-
140-
### Parameters for `teamsapp validate`
141-
142-
| Parameters | Required | Descriptions |
143-
|:---------------- |:-------------|:-------------|
144-
|`manifest-file`| No | Specifies the Microsoft Teams app manifest file path. Default value: "./appPackage/manifest.json".|
145-
|`package-file`| No | Specifies the zipped Microsoft Teams app package file path.|
146-
|`output-package-file`| No | Specifies the output zipped Microsoft Teams app package file path. Default value: "./appPackage/build/appPackage.${env}.zip".|
147-
|`output-manifest-file`| No | Specifies the output Microsoft Teams app manifest file path. Default value: "./appPackage/build/manifest.${env}.json".|
148-
|`env`| No | Specifies the environment name for the project scaffolded by Microsoft Teams Toolkit.|
149-
|`env-file`| No | Specifies the .env file that defines the variables to replace in the Teams app manifest template file.|
150-
|`folder`| No | Project folder. Default value: "./". |
151-
152-
## `teamsapp publish`
153-
154-
Publish the app to Teams.
155-
156-
### Parameters for `teamsapp publish`
157-
158-
| Parameters | Required | Descriptions |
159-
|:---------------- |:-------------|:-------------|
160-
|`manifest-file`| No | Specifies the Microsoft Teams app manifest file path. Default value: "./appPackage/manifest.json".|
161-
|`package-file`| No | Specifies the zipped Microsoft Teams app package file path.|
162-
|`output-package-file`| No | Specifies the output zipped Microsoft Teams app package file path. Default value: "./appPackage/build/appPackage.${env}.zip".|
163-
|`output-manifest-file`| No | Specifies the output Microsoft Teams app manifest file path. Default value: "./appPackage/build/manifest.${env}.json".|
164-
|`env`| No | Specifies the environment name for the project scaffolded by Microsoft Teams Toolkit.|
165-
|`env-file`| No | Specifies the .env file that defines the variables to replace in the Teams app manifest template file.|
166-
|`folder`| No | Project folder. Default value: "./". |
167-
168-
## `teamsapp package`
169-
170-
Build your Teams app into a package for publishing.
171-
### Parameters for `teamsapp publish`
172-
173-
| Parameters | Required | Descriptions |
174-
|:---------------- |:-------------|:-------------|
175-
|`manifest-file`| No | Specifies the Microsoft Teams app manifest file path. Default value: "./appPackage/manifest.json".|
176-
|`output-package-file`| No | Specifies the output zipped Microsoft Teams app package file path. Default value: "./appPackage/build/appPackage.${env}.zip".|
177-
|`output-manifest-file`| No | Specifies the output Microsoft Teams app manifest file path. Default value: "./appPackage/build/manifest.${env}.json".|
178-
|`env`| No | Specifies the environment name for the project scaffolded by Microsoft Teams Toolkit.|
179-
|`env-file`| No | Specifies the .env file that defines the variables to replace in the Teams app manifest template file.|
180-
|`folder`| No | Project folder. Default value: "./". |
181-
182-
## `teamsapp preview`
183-
184-
Preview the current application from local or remote.
5+
> [!IMPORTANT]
6+
> This user manual has been moved to [Teams platform development documentation](https://aka.ms/teamsfx-cli) and will no longer be updated. Please refer to the new documentation for the latest information.
1857
186-
### Parameters for `teamsapp preview`
8+
## Additional References
1879

188-
| Parameters | Required | Descriptions |
189-
|:---------------- |:-------------|:-------------|
190-
|`m365-host` | No | Preview the application in Teams, Outlook or the Microsoft 365 app. Allowed value: ["teams", "outlook", "office"]. Default value: "teams".|
191-
|`teams-manifest-file` | No | Specifies the Microsoft Teams app manifest template file path, it can be either absolute path or relative path to project root folder, defaults to './appPackage/manifest.json' Default value: "./appPackage/manifest.json".|
192-
|`run-command` | No | The command to start local service. Work for 'local' environment only. If undefined, teamsfx will use the auto detected one from project type (`npm run dev:teamsfx` or `dotnet run` or `func start`). If empty, teamsfx will skip starting local service. |
193-
|`running-pattern` | No | The ready signal output that service is launched. Work for 'local' environment only. If undefined, teamsfx will use the default common pattern ("started|successfully|finished|crashed|failed|listening"). If empty, teamsfx treats process start as ready signal. |
194-
|`open-only` | No | Work for 'local' environment only. If true, directly open web client without launching local service. Default value: false. |
195-
|`browser` | No | Select browser to open Microsoft Teams web client. Allowed value: ["chrome", "edge", "default"]. Default value: "default".|
196-
|`browser-arg` | No | Argument to pass to the browser (e.g. --browser-args="--guest") |
197-
|`exec-path` | No | The paths that will be added to the system environment variable PATH when the command is executed, defaults to "${folder}/devTools/func". Default value: "devTools/func". |
198-
|`env` | No | Specifies the environment name for the project. Default value: "local".|
199-
|`folder` | No | Project folder. Default value: "./".|
200-
201-
### Scenarios for `teamsapp preview`
202-
203-
#### Local Preview
204-
205-
Dependencies:
206-
207-
- Node.js
208-
- .NET SDK
209-
- Azure Functions Core Tools
210-
211-
```bash
212-
teamsapp preview --env local
213-
teamsapp preview --env local --browser chrome
214-
```
215-
216-
#### Remote Preview
217-
218-
```bash
219-
teamsapp preview --env dev
220-
teamsapp preview --env dev --browser edge
221-
```
222-
223-
> [!Note]
224-
> The logs of the background services like React will be saved in `~/.fx/cli-log/local-preview/`.
225-
226-
## `teamsapp collaborator`
227-
228-
teamsapp CLI provides `teamsapp collaborator` Commands for collaboration scenario.
229-
230-
| `teamsapp collaborator` Commands | Descriptions |
231-
|:------------------------------|-------------|
232-
| `teamsapp collaborator grant --env --email` | Grant permission for collaborator's Microsoft 365 account for the project of a specified environment. |
233-
| `teamsapp collaborator status` | Show permission status for the project |
234-
235-
### Parameters for `teamsapp collaborator grant`
236-
237-
| Parameters | Required | Descriptions |
238-
|:---------------- |:-------------|:-------------|
239-
|`--env`| Yes | Provide env name. |
240-
|`--email`| Yes | Provide collaborator's Microsoft 365 email address. Note that the collaborator's account should be in the same tenant with creator. |
241-
242-
### Parameters for `teamsapp collaborator status`
243-
244-
| Parameters | Required | Descriptions |
245-
|:---------------- |:-------------|:-------------|
246-
|`--env`| Yes | Provide env name. |
247-
|`--list-all-collaborators` | No | With this flag, Teams Toolkit CLI will print out all collaborators for this project. |
248-
249-
### Scenarios for `teamsapp collaborator`
250-
251-
Here are some examples, for better handling permission for `teamsapp` projects.
252-
253-
#### Grant Permission
254-
255-
Project creator and collaborators can use `teamsapp collaborator grant` command to add a new collaborator to the project:
256-
257-
```bash
258-
teamsapp collaborator grant --env dev --email [email protected]
259-
```
260-
261-
After successfully granted permission, project creator and collaborators can share the project with the new collaborator by Github, and the new collaborator will have all permission for Microsoft 365 account.
262-
263-
#### Show Permission Status
264-
265-
Project creator and collaborators can use `teamsapp collaborator status` command to view his Microsoft 365 account permission for specific env:
266-
267-
```bash
268-
teamsapp collaborator status --env dev
269-
```
270-
271-
#### List All Collaborators
272-
273-
Project creator and collaborators can use `teamsapp collaborator status` command to view all collaborators for specific env:
274-
275-
```bash
276-
teamsapp collaborator status --env dev --list-all-collaborators
277-
```
278-
279-
#### E2E Collaboration work flow in CLI
280-
281-
As a project creator:
282-
283-
- Create a new teamsapp Tab project (You can also select bot).
284-
285-
```bash
286-
teamsapp new -c notification -t timer-functions -l typescript -n myapp -i false
287-
```
288-
289-
- Login Microsoft 365 account and Azure account.
290-
291-
```bash
292-
teamsapp auth login azure
293-
teamsapp auth login m365
294-
```
295-
296-
- Provision your project.
297-
298-
```bash
299-
teamsapp provision
300-
```
301-
302-
- View collaborators. You should see yourself here.
303-
304-
```bash
305-
teamsapp collaborator status --env dev --list-all-collaborators
306-
```
307-
308-
![list-all-collaborators](TODO)
309-
- Add another account as collaborator. Note that the added account must under the same tenant:
310-
311-
```bash
312-
teamsapp collaborator grant --env dev --email [email protected]
313-
```
314-
315-
![add-new-collaborator](TODO)
316-
- Push your project to GitHub
317-
318-
As a Project Collaborator:
319-
320-
- Clone the project from GitHub.
321-
- Login Microsoft 365 account. Note that the Microsoft 365 account should be the same as added above:
322-
323-
```bash
324-
teamsapp auth login m365
325-
```
326-
327-
- Login Azure account which has contributor permission for all the Azure resources.
328-
329-
```bash
330-
teamsapp auth login azure
331-
```
332-
333-
- Check permission status. You should find yourself have the owner permission of the project:
10+
* [Source code](https://github.com/OfficeDev/teamsapp/tree/dev/packages/cli)
11+
* [Package (NPM)](https://www.npmjs.com/package/@microsoft/teamsapp-cli)
12+
* [Official Documentation](https://aka.ms/teamsfx-cli)
33413

335-
```bash
336-
teamsapp collaborator status --env dev
337-
```
14+
## Feedback
33815

339-
![collaborator status](TODO)
340-
- Update Tab code, and deploy the project to remote.
341-
- Launch remote and the project should work fine.
16+
- Ask a question on [Stack Overflow](https://stackoverflow.com/questions/tagged/teams-toolkit)
17+
- [Request a new feature](https://github.com/OfficeDev/TeamsFx/issues/new?assignees=&labels=&template=feature_request.md&title=)
18+
- [File an issue](https://github.com/OfficeDev/TeamsFx/issues/new?assignees=&labels=&template=bug_report.md&title=)
19+
- Send an email to [email protected] to chat with the product team
20+
- Report security issues and bugs to the Microsoft Security Response Center (MSRC) via [email protected]. Further information can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue?rtc=1).

0 commit comments

Comments
 (0)