README.md
1# libnpmteam [](https://npm.im/libnpmteam) [](https://npm.im/libnpmteam) [](https://travis-ci.org/npm/libnpmteam) [](https://ci.appveyor.com/project/zkat/libnpmteam) [](https://coveralls.io/github/npm/libnpmteam?branch=latest)
2
3[`libnpmteam`](https://github.com/npm/libnpmteam) is a Node.js
4library that provides programmatic access to the guts of the npm CLI's `npm
5team` command and its various subcommands.
6
7## Example
8
9```javascript
10const access = require('libnpmteam')
11
12// List all teams for the @npm org.
13console.log(await team.lsTeams('npm'))
14```
15
16## Table of Contents
17
18* [Installing](#install)
19* [Example](#example)
20* [Contributing](#contributing)
21* [API](#api)
22 * [team opts](#opts)
23 * [`create()`](#create)
24 * [`destroy()`](#destroy)
25 * [`add()`](#add)
26 * [`rm()`](#rm)
27 * [`lsTeams()`](#ls-teams)
28 * [`lsTeams.stream()`](#ls-teams-stream)
29 * [`lsUsers()`](#ls-users)
30 * [`lsUsers.stream()`](#ls-users-stream)
31
32### Install
33
34`$ npm install libnpmteam`
35
36### Contributing
37
38The npm team enthusiastically welcomes contributions and project participation!
39There's a bunch of things you can do if you want to contribute! The [Contributor
40Guide](CONTRIBUTING.md) has all the information you need for everything from
41reporting bugs to contributing entire new features. Please don't hesitate to
42jump in if you'd like to, or even ask us questions if something isn't clear.
43
44All participants and maintainers in this project are expected to follow [Code of
45Conduct](CODE_OF_CONDUCT.md), and just generally be excellent to each other.
46
47Please refer to the [Changelog](CHANGELOG.md) for project history details, too.
48
49Happy hacking!
50
51### API
52
53#### <a name="opts"></a> `opts` for `libnpmteam` commands
54
55`libnpmteam` uses [`npm-registry-fetch`](https://npm.im/npm-registry-fetch).
56All options are passed through directly to that library, so please refer to [its
57own `opts`
58documentation](https://www.npmjs.com/package/npm-registry-fetch#fetch-options)
59for options that can be passed in.
60
61A couple of options of note for those in a hurry:
62
63* `opts.token` - can be passed in and will be used as the authentication token for the registry. For other ways to pass in auth details, see the n-r-f docs.
64* `opts.otp` - certain operations will require an OTP token to be passed in. If a `libnpmteam` command fails with `err.code === EOTP`, please retry the request with `{otp: <2fa token>}`
65* `opts.Promise` - If you pass this in, the Promises returned by `libnpmteam` commands will use this Promise class instead. For example: `{Promise: require('bluebird')}`
66
67#### <a name="create"></a> `> team.create(team, [opts]) -> Promise`
68
69Creates a team named `team`. Team names use the format `@<scope>:<name>`, with
70the `@` being optional.
71
72Additionally, `opts.description` may be passed in to include a description.
73
74##### Example
75
76```javascript
77await team.create('@npm:cli', {token: 'myregistrytoken'})
78// The @npm:cli team now exists.
79```
80
81#### <a name="destroy"></a> `> team.destroy(team, [opts]) -> Promise`
82
83Destroys a team named `team`. Team names use the format `@<scope>:<name>`, with
84the `@` being optional.
85
86##### Example
87
88```javascript
89await team.destroy('@npm:cli', {token: 'myregistrytoken'})
90// The @npm:cli team has been destroyed.
91```
92
93#### <a name="add"></a> `> team.add(user, team, [opts]) -> Promise`
94
95Adds `user` to `team`.
96
97##### Example
98
99```javascript
100await team.add('zkat', '@npm:cli', {token: 'myregistrytoken'})
101// @zkat now belongs to the @npm:cli team.
102```
103
104#### <a name="rm"></a> `> team.rm(user, team, [opts]) -> Promise`
105
106Removes `user` from `team`.
107
108##### Example
109
110```javascript
111await team.rm('zkat', '@npm:cli', {token: 'myregistrytoken'})
112// @zkat is no longer part of the @npm:cli team.
113```
114
115#### <a name="ls-teams"></a> `> team.lsTeams(scope, [opts]) -> Promise`
116
117Resolves to an array of team names belonging to `scope`.
118
119##### Example
120
121```javascript
122await team.lsTeams('@npm', {token: 'myregistrytoken'})
123=>
124[
125 'npm:cli',
126 'npm:web',
127 'npm:registry',
128 'npm:developers'
129]
130```
131
132#### <a name="ls-teams-stream"></a> `> team.lsTeams.stream(scope, [opts]) -> Stream`
133
134Returns a stream of teams belonging to `scope`.
135
136For a Promise-based version of these results, see [`team.lsTeams()`](#ls-teams).
137
138##### Example
139
140```javascript
141for await (let team of team.lsTeams.stream('@npm', {token: 'myregistrytoken'})) {
142 console.log(team)
143}
144
145// outputs
146// npm:cli
147// npm:web
148// npm:registry
149// npm:developers
150```
151
152#### <a name="ls-users"></a> `> team.lsUsers(team, [opts]) -> Promise`
153
154Resolves to an array of usernames belonging to `team`.
155
156For a streamed version of these results, see [`team.lsUsers.stream()`](#ls-users-stream).
157
158##### Example
159
160```javascript
161await team.lsUsers('@npm:cli', {token: 'myregistrytoken'})
162=>
163[
164 'iarna',
165 'zkat'
166]
167```
168
169#### <a name="ls-users-stream"></a> `> team.lsUsers.stream(team, [opts]) -> Stream`
170
171Returns a stream of usernames belonging to `team`.
172
173For a Promise-based version of these results, see [`team.lsUsers()`](#ls-users).
174
175##### Example
176
177```javascript
178for await (let user of team.lsUsers.stream('@npm:cli', {token: 'myregistrytoken'})) {
179 console.log(user)
180}
181
182// outputs
183// iarna
184// zkat
185```
186
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}