Cleaned up dart pub token

Author: Tony Sansone

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

@@ -3,19 +3,18 @@ title: dart pub token
 description: Manage authentication tokens for package repositories.
 ---
 
-_pub_ _token_ is one of the subcommands of the [pub command](/tools/pub/cmd).
+The `dart pub token` subcommand manages a store of secret tokens to
+authenticate against third-party servers when [publishing](pub-lish) packages
+and [retrieving](pub-get) dependencies.
 
-It is used to manage a store of secret tokens for authenticating
-against third-party servers when [publishing](pub-lish) packages and
-[retrieving](pub-get) dependencies.
-
-The tokens are stored in a
-[user-wide config dir]({{site.repo.dart.org}}/cli_util/blob/71ba36e2554f7b7717f3f12b5ddd33751a4e3ddd/lib/cli_util.dart#L88-L118). 
+It stores these tokens in a [user-wide config directory][config-dir].
 
 It has three subcommands: `add`, `list` and `remove`.
 
-If you try to `dart pub get` and have a [dependency](/tools/pub/dependencies) hosted
-on a private repository you _may_ be asked to provide credentials:
+Consider a scenario when you have a [dependency](/tools/pub/dependencies)
+hosted on a private repository.
+When you invoke `dart pub get`, the command _might_ return a prompt
+to provide credentials:
 
 ```console
 $ dart pub get
@@ -26,13 +25,16 @@ https://some-package-repo.com/my-org/my-repo package repository requested authen
 Go to https://some-package-repo.com and log in to obtain your token. 
 ```
 
-The last line is a message the server can provide to help you obtaining a token.
-Some servers might not provide such a message.
+In this last message, the final line gives you the server that can help you
+obtain a token. Not all servers provide such this message.
+
+## Add a new credential
+
+To create a new credential, invoke `dart pub token add`.
 
-## Adding credentials `dart pub token add`
+### Add a credential for the current session
 
-To enter the credentials use `dart pub token add`, 
-and type the credential on stdin.
+At the prompt, type the credential on the command line (`stdin`).
 
 ```console
 $ dart pub token add https://some-package-repo.com/my-org/my-repo
@@ -42,33 +44,45 @@ Enter secret token: <Type token on stdin>
 ```
 
 :::note
-The token is input on stdin rather than as a command line option to avoid it
-ending up in the shell history such as `~/.bash_history`.
+The token takes input on `stdin` rather than as a command line option
+to keep the token out of the shell history.
 :::
 
-In a scripting situation you can store the secret in an environment variable and
-use `dart pub token add <hosted-url> --env-var <ENV_VAR_NAME>`.
+### Add a credential for all sessions
 
-```console
-$ dart pub token add https://other-package-repo.com/ --env-var TOKEN_VAR
-Requests to "https://other-package-repo.com/" will now be authenticated using the secret token stored in the environment variable "TOKEN_VAR".
-```
+In a script, you can store the secret in an environment variable.
+
+If you choose to store your secret in an environment variable,
+find a way to hide the secret from your shell history.
+To explore one way of doing this, consult [this post on Medium][zsh-post].
+If you add a local environment variable, you need to restart any open
+consoles to enable that new variable.
+
+Most CI environments can inject secrets into an environment variable.
+To learn how, consult documentation for [GitHub Actions][]] or
+[GitLab][] as examples.
 
-This will cause `dart pub get` to read whatever is stored in `$TOKEN_VAR` and
-use that as the authentication token.
+[GitHub Actions]: https://docs.github.com/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow
+[GitLab]: https://docs.gitlab.com/ee/ci/secrets/
+[zsh-post]: https://medium.com/@prasincs/hiding-secret-keys-from-shell-history-part-1-5875eb5556cc
 
-You can set the environment variable in Bash with `export TOKEN_VAR=...` but
-that still doesn't prevent the command being logged.
+To use an environment variable as a token, invoke:
 
-Most CI environments has a way to inject secrets into an environment
-variable:
+```console
+dart pub token add <hosted-url> --env-var <ENV_VAR_NAME>
+```
 
-* [GitHub Actions](https://docs.github.com/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow).
-* [GitLab](https://docs.gitlab.com/ee/ci/secrets/).
+This causes `dart pub get` to read the data stored in `$TOKEN_VAR` then
+use it as the authentication token.
 
-## Listing credentials `dart pub token list`
+```console
+$ dart pub token add https://other-package-repo.com/ --env-var TOKEN_VAR
+Requests to "https://other-package-repo.com/" will now be authenticated using the secret token stored in the environment variable "TOKEN_VAR".
+```
+
+## Return a list of credentials
 
-To see a list of all active credentials use `dart pub token list`:
+To see a list of all active credentials, invoke `dart pub token list`:
 
 ```console
 $ dart pub token list
@@ -77,22 +91,23 @@ https://some-package-repo.com/my-org/my-repo
 https://other-package-repo.com/
 ```
 
-## Removing credentials `dart pub token remove`
+## Remove one or more credentials
 
-You can remove a single token with `dart pub token remove`:
+To remove a single token, invoke `dart pub token remove`:
 
 ```console
 $ dart pub token remove https://other-package-repo.com
 Removed secret token for package repository: https://other-package-repo.com
 ```
 
-Or remove all with `remove --all`:
+To remove all tokens, invoke the command with the `remove --all` option:
 
 ```console
 $ dart pub token remove --all
 pub-tokens.json is deleted.
 Removed 1 secret tokens.
 ```
 
-
 {% include 'pub-problems.md' %}
+
+[config-dir]: {{site.repo.dart.org}}/cli_util/blob/71ba36e2554f7b7717f3f12b5ddd33751a4e3ddd/lib/cli_util.dart#L88-L118