Skip to content

Commit 1074d75

Browse files
author
Tony Sansone
committed
Update after copy review
1 parent 2af2506 commit 1074d75

File tree

1 file changed

+53
-31
lines changed

1 file changed

+53
-31
lines changed

src/content/tools/pub/cmd/pub-token.md

+53-31
Original file line numberDiff line numberDiff line change
@@ -3,40 +3,46 @@ title: dart pub token
33
description: Manage authentication tokens for package repositories.
44
---
55

6-
The `dart pub token` subcommand manages a store of secret tokens to
7-
authenticate against third-party servers when [publishing](pub-lish) packages
8-
and [retrieving](pub-get) dependencies.
6+
The `dart pub token` subcommand manages a store of tokens.
7+
When [publishing](pub-lish) packages and [retrieving](pub-get) dependencies,
8+
the `dart pub` command uses tokens to authenticate against third-party servers.
99

1010
It stores these tokens in a [user-wide config directory][config-dir].
11+
The `dart pub token` subcommand has three subcommands:
12+
[`add`][], [`list`][] and [`remove`][].
1113

12-
This command has three subcommands: `add`, `list`, and `remove`.
14+
The `dart pub` command considers the terms _credential_, _token_, _secret_,
15+
and _secret token_ to be interchangable.
1316

14-
Consider a scenario where you have a [dependency](/tools/pub/dependencies)
17+
[`add`]: #add-a-new-credential
18+
[`list`]: #return-a-list-of-credentials
19+
[`remove`]: #remove-one-or-more-credentials
20+
21+
## Use case for credentials
22+
23+
Consider a scenario when you have a [dependency](/tools/pub/dependencies)
1524
hosted on a private repository.
1625
When you invoke `dart pub get`, the command _might_ return a prompt
1726
to provide credentials:
1827

1928
```console
2029
$ dart pub get
2130
Resolving dependencies...
22-
https://some-package-repo.com/my-org/my-repo package repository requested authentication! You can provide credential using:
23-
pub token add https://some-package-repo.com/my-org/my-repo
24-
25-
Go to https://some-package-repo.com and log in to obtain your token.
31+
https://some-package-repo.com/my-org/my-repo package repository requested authentication!
32+
You can provide credentials using:
33+
dart pub token add https://some-package-repo.com/my-org/my-repo
2634
```
2735

28-
The server might include a message in the final line of the prompt
29-
to help you obtain a token.
30-
This message is displayed in the previous example.
31-
Not all servers provide this message.
36+
Some, but not all, servers also return a message with instructions as
37+
to how you can obtain a token.
3238

3339
## Add a new credential
3440

35-
To add a new credential, run the command `dart pub token add`.
41+
To create a new credential, invoke `dart pub token add`.
3642

3743
### Add a credential for the current session
3844

39-
At the prompt, type the credential on the command line.
45+
At the prompt, type the credential on the command line (`stdin`).
4046

4147
```console
4248
$ dart pub token add https://some-package-repo.com/my-org/my-repo
@@ -46,34 +52,51 @@ Enter secret token: <Type token on stdin>
4652
```
4753

4854
:::note
49-
The token takes input over `stdin` rather than as a command line option
50-
to keep the token out of the shell history.
55+
To keep the token out of the shell history,
56+
the `dart pub token` command takes input on `stdin` rather than
57+
as a command line option.
5158
:::
5259

5360
### Add a credential for all sessions
5461

55-
In a script, you can store the secret in an environment variable.
62+
To use the same token for any and all terminal sessions and in scripts,
63+
store the token in an environment variable.
64+
65+
1. Store your token in an environment variable.
66+
67+
Make sure to hide the token from your shell history.
68+
To explore one way of doing this, consult [this post on Medium][zsh-post].
69+
70+
1. To enable any environment variables that you add,
71+
restart any open consoles.
72+
73+
1. To use an environment variable as a token, run the following command:
5674

57-
If you choose to store your token in an environment variable,
58-
[find a way][zsh-post] to hide the token from your shell history.
59-
If you add an environment variable, you need to restart any open
60-
consoles to enable that new variable.
75+
```console
76+
$ dart pub token add <hosted-url> --env-var <TOKEN_VAR>
77+
```
78+
79+
This command reads the token stored in `$TOKEN_VAR`
80+
then uses it to authenticate with the `hosted-url`
81+
hosting the desired package.
82+
It should print the following response to the terminal.
83+
84+
```console
85+
$ dart pub token add https://other-package-repo.com/ --env-var TOKEN_VAR
86+
Requests to "https://other-package-repo.com/" will now be authenticated using the secret token stored in the environment variable "TOKEN_VAR".
87+
```
6188

6289
Most CI environments can inject tokens into an environment variable.
63-
To learn how, consult documentation for [GitHub Actions][] or
90+
To learn how, consult documentation for [GitHub Actions][]] or
6491
[GitLab][] as examples.
6592

6693
[GitHub Actions]: https://docs.github.com/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow
6794
[GitLab]: https://docs.gitlab.com/ee/ci/secrets/
6895
[zsh-post]: https://medium.com/@prasincs/hiding-secret-keys-from-shell-history-part-1-5875eb5556cc
6996

70-
71-
72-
73-
7497
## Return a list of credentials
7598

76-
To see a list of all active credentials, run the command `dart pub token list`:
99+
To see a list of all active credentials, invoke `dart pub token list`:
77100

78101
```console
79102
$ dart pub token list
@@ -84,15 +107,14 @@ https://other-package-repo.com/
84107

85108
## Remove one or more credentials
86109

87-
To remove a single token, run the command `dart pub token remove`:
110+
To remove a single token, invoke `dart pub token remove`:
88111

89112
```console
90113
$ dart pub token remove https://other-package-repo.com
91114
Removed secret token for package repository: https://other-package-repo.com
92115
```
93116

94-
To remove all tokens,
95-
run the same command and append the `--all` option:
117+
To remove all tokens, invoke the command with the `remove --all` option:
96118

97119
```console
98120
$ dart pub token remove --all

0 commit comments

Comments
 (0)