From b0ea806146a10f298fc7d5e95351d9f1798b20e9 Mon Sep 17 00:00:00 2001 From: Tom Payne Date: Thu, 24 Mar 2022 10:08:23 +0100 Subject: [PATCH] chore: Tidy up 1Password docs --- .../templates/functions/onepassword.md | 36 ++++++++--------- .../functions/onepasswordDetailsFields.md | 13 ++---- .../functions/onepasswordDocument.md | 29 +++++--------- .../functions/onepasswordItemFields.md | 19 +++------ .../user-guide/password-managers/1password.md | 40 +++++++++---------- 5 files changed, 54 insertions(+), 83 deletions(-) diff --git a/assets/chezmoi.io/docs/reference/templates/functions/onepassword.md b/assets/chezmoi.io/docs/reference/templates/functions/onepassword.md index d22ce4f5c5c..6c5dd851d7d 100644 --- a/assets/chezmoi.io/docs/reference/templates/functions/onepassword.md +++ b/assets/chezmoi.io/docs/reference/templates/functions/onepassword.md @@ -2,14 +2,15 @@ `onepassword` returns structured data from [1Password](https://1password.com/) using the [1Password -CLI](https://support.1password.com/command-line-getting-started/) (`op`). *uuid* -is passed to `op item get $UUID --format json` and the output from `op`. The -output from `op` is cached so calling `onepassword` multiple times with the same -*uuid* will only invoke `op` once. If the optional *vault-uuid* is supplied, it -will be passed along to the `op item get` call, which can significantly improve -performance. If the optional *account-name* is supplied, it will be passed along -to the `op item get` call, which will help it look in the right account, in case -you have multiple accounts (e.g., personal and work accounts). +CLI](https://support.1password.com/command-line-getting-started/) (`op`). +*uuid* is passed to `op item get $UUID --format json` and the output from `op` +is parsed as JSON. The output from `op` is cached so calling `onepassword` +multiple times with the same *uuid* will only invoke `op` once. If the optional +*vault-uuid* is supplied, it will be passed along to the `op item get` call, +which can significantly improve performance. If the optional *account-name* is +supplied, it will be passed along to the `op item get` call, which will help it +look in the right account, in case you have multiple accounts (e.g., personal +and work accounts). If there is no valid session in the environment, by default you will be interactively prompted to sign in. @@ -27,11 +28,13 @@ interactively prompted to sign in. ``` {{ range (onepassword "$UUID").fields -}} - {{- if and (eq .label "password") (eq .purpose "PASSWORD") }}{{ .value }}{{ end -}} - {{- end }} + {{ if and (eq .label "password") (eq .purpose "PASSWORD") -}} + {{ .value -}} + {{ end -}} + {{ end }} ``` - ??? info + !!! info For 1Password CLI 1.x. @@ -54,7 +57,7 @@ interactively prompted to sign in. the other functions. Testing the output of this function is recommended: ```console - chezmoi execute-template "{{- onepassword \"$UUID\" | toJson -}}" | jq . + $ chezmoi execute-template "{{ onepassword \"$UUID\" | toJson }}" | jq . ``` !!! warning @@ -65,13 +68,6 @@ interactively prompted to sign in. using *account-name*, it is recommended that you use the *account-uuid*. This can be found using `op account list`. - This issue does not exist when using biometric authentication and 1Password + This issue does not occur when using biometric authentication and 1Password 8, or if you allow chezmoi to prompt you for 1Password authentication (`1password.prompt = true`). - -!!! info - - In earlier versions of chezmoi, if *vault-uuid* or *account-name* were - empty strings, they would be added to the resulting `op` command-line - (`--vault ''`). This causes errors in 1Password CLI 2.0, so those arguments - will no longer be added. diff --git a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDetailsFields.md b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDetailsFields.md index 339cbbf2fd8..88b71b986f9 100644 --- a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDetailsFields.md +++ b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDetailsFields.md @@ -13,7 +13,7 @@ times with the same *uuid* will only invoke `op` once. If the optional *vault-uuid* is supplied, it will be passed along to the `op get` call, which can significantly improve performance. If the optional *account-name* is supplied, it will be passed along to the `op get` call, which will help it look -in the right account, in case you have multiple accounts (e.g., personal and +in the right account, in case you have multiple accounts (e.g. personal and work accounts). !!! example @@ -81,7 +81,7 @@ work accounts). function is recommended: ```console - chezmoi execute-template "{{- onepasswordDetailsFields \"$UUID\" | toJson -}}" | jq . + $ chezmoi execute-template "{{ onepasswordDetailsFields \"$UUID\" | toJson }}" | jq . ``` !!! warning @@ -92,13 +92,6 @@ work accounts). using *account-name*, it is recommended that you use the *account-uuid*. This can be found using `op account list`. - This issue does not exist when using biometric authentication and 1Password + This issue does not occur when using biometric authentication and 1Password 8, or if you allow chezmoi to prompt you for 1Password authentication (`1password.prompt = true`). - -!!! info - - In earlier versions of chezmoi, if *vault-uuid* or *account-name* were - empty strings, they would be added to the resulting `op` command-line - (`--vault ''`). This causes errors in 1Password CLI 2.0, so those arguments - will no longer be added. diff --git a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDocument.md b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDocument.md index 9fbed7f6f65..5e402a98764 100644 --- a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDocument.md +++ b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordDocument.md @@ -2,16 +2,16 @@ `onepasswordDocument` returns a document from [1Password](https://1password.com/) using the [1Password -CLI](https://support.1password.com/command-line-getting-started/) (`op`). *uuid* -is passed to `op get document $UUID` and the output from `op` is returned. The -output from `op` is cached so calling `onepasswordDocument` multiple times with -the same *uuid* will only invoke `op` once. If the optional *vault-uuid* is -supplied, it will be passed along to the `op get` call, which can significantly -improve performance. If the optional *account-name* is supplied, it will be -passed along to the `op get` call, which will help it look in the right account, -in case you have multiple accounts (e.g., personal and work accounts). If there -is no valid session in the environment, by default you will be interactively -prompted to sign in. +CLI](https://support.1password.com/command-line-getting-started/) (`op`). +*uuid* is passed to `op get document $UUID` and the output from `op` is +returned. The output from `op` is cached so calling `onepasswordDocument` +multiple times with the same *uuid* will only invoke `op` once. If the optional +*vault-uuid* is supplied, it will be passed along to the `op get` call, which +can significantly improve performance. If the optional *account-name* is +supplied, it will be passed along to the `op get` call, which will help it look +in the right account, in case you have multiple accounts (e.g., personal and +work accounts). If there is no valid session in the environment, by default you +will be interactively prompted to sign in. !!! example @@ -31,13 +31,6 @@ prompted to sign in. recommended that you use the *account-uuid*. This can be found using `op account list`. - This issue does not exist when using biometric authentication and 1Password + This issue does not occur when using biometric authentication and 1Password 8, or if you allow chezmoi to prompt you for 1Password authentication (`1password.prompt = true`). - -!!! info - - In earlier versions of chezmoi, if *vault-uuid* or *account-name* were - empty strings, they would be added to the resulting `op` command-line - (`--vault ''`). This causes errors in 1Password CLI 2.0, so those arguments - will no longer be added. diff --git a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordItemFields.md b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordItemFields.md index 2da73414462..916f2f166af 100644 --- a/assets/chezmoi.io/docs/reference/templates/functions/onepasswordItemFields.md +++ b/assets/chezmoi.io/docs/reference/templates/functions/onepasswordItemFields.md @@ -1,8 +1,8 @@ -# `onepasswordItemFields` _uuid_ [_vault-uuid_ [*account-name*]] +# `onepasswordItemFields` *uuid* [*vault-uuid* [*account-name*]] `onepasswordItemFields` returns structured data from [1Password](https://1password.com/) using the [1Password -CLI](https://support.1password.com/command-line-getting-started/) (`op`). _uuid_ +CLI](https://support.1password.com/command-line-getting-started/) (`op`). *uuid* is passed to `op item get $UUID --format json`, the output from `op` is parsed as JSON, and each element of `details.sections` are iterated over and any `fields` are returned as a map indexed by each field's `n`. @@ -26,7 +26,7 @@ interactively prompted to sign in. $ op item get abcdefghijklmnopqrstuvwxyz --fields exampleLabel ``` - ??? info + !!! info For 1Password CLI 1.x. @@ -85,7 +85,7 @@ interactively prompted to sign in. } ``` - ??? info + !!! info For 1Password CLI 1.x, the output is this: @@ -139,7 +139,7 @@ interactively prompted to sign in. this function is recommended: ```console - chezmoi execute-template "{{- onepasswordItemFields \"$UUID\" | toJson -}}" | jq . + $ chezmoi execute-template "{{ onepasswordItemFields \"$UUID\" | toJson }}" | jq . ``` !!! warning @@ -150,13 +150,6 @@ interactively prompted to sign in. using *account-name*, it is recommended that you use the *account-uuid*. This can be found using `op account list`. - This issue does not exist when using biometric authentication and 1Password + This issue does not occur when using biometric authentication and 1Password 8, or if you allow chezmoi to prompt you for 1Password authentication (`1password.prompt = true`). - -!!! info - - In earlier versions of chezmoi, if *vault-uuid* or *account-name* were - empty strings, they would be added to the resulting `op` command-line - (`--vault ''`). This causes errors in 1Password CLI 2.0, so those arguments - will no longer be added. diff --git a/assets/chezmoi.io/docs/user-guide/password-managers/1password.md b/assets/chezmoi.io/docs/user-guide/password-managers/1password.md index f6b7807adfe..6c72b8ef20f 100644 --- a/assets/chezmoi.io/docs/user-guide/password-managers/1password.md +++ b/assets/chezmoi.io/docs/user-guide/password-managers/1password.md @@ -6,22 +6,24 @@ expose data as a template function. !!! note - [1Password CLI 2.0](https://developer.1password.com/) has been released. + The[1Password CLI 2.0](https://developer.1password.com/) has been released. Examples will be shown using the changed details for this version and examples for 1Password CLI 1.x will follow. Log in and get a session using: ```console -# For 1Password 2.x. Neither step is necessary with biometric authentication. $ op account add --address $SUBDOMAIN.1password.com --email $EMAIL $ eval $(op signin --account $SUBDOMAIN) ``` -??? info +This is not necessary if you are using biometric authentication. + +!!! info + + For 1Password CLI 1.x, use: ```console - # For 1Password 1.x $ eval $(op signin $SUBDOMAIN.1password.com $EMAIL) ``` @@ -80,11 +82,13 @@ or: ``` {{ range (onepassword "$UUID").fields -}} -{{- if and (eq .label "password") (eq .purpose "PASSWORD") }}{{ .value }}{{ end -}} -{{- end }} +{{ if and (eq .label "password") (eq .purpose "PASSWORD") -}} +{{ .value -}} +{{ end -}} +{{ end }} ``` -??? info +!!! info 1Password CLI 1.x returns a simpler structure: @@ -134,10 +138,10 @@ allows the fields to be queried by key: ``` Additional fields may be obtained with `onePasswordItemFields`; not all objects -in 1Password have item fields, so it is worth testing before using: +in 1Password have item fields. This can be tested with: ```console -chezmoi execute-template "{{- onepasswordItemFields \"$UUID\" | toJson -}}" | jq . +$ chezmoi execute-template "{{ onepasswordItemFields \"$UUID\" | toJson }}" | jq . ``` Documents can be retrieved with: @@ -153,15 +157,15 @@ Documents can be retrieved with: substitution. This removes any trailing newline added by your editor when saving the template. -## 1Password sign-in prompt +## Sign-in prompt chezmoi will verify the availability and validity of a session token in the current environment. If it is missing or expired, you will be interactively prompted to sign-in again. In the past chezmoi used to simply exit with an error when no valid session was -available. If you'd like to restore that behavior, set the following option in -your configuration file: +available. If you'd like to restore this behavior, set the the +`onepassword.prompt` configuration variable to `false`, for example: ```toml title="~/.config/chezmoi/chezmoi.toml" [onepassword] @@ -171,13 +175,5 @@ your configuration file: !!! danger Do not use the prompt on shared machines. A session token verified or - acquired interactively will be passed to the 1Password CLI through a command - line parameter, which is visible to other users of the same system. - -!!! info - - If you're using [1Password CLI - 2.0](https://developer.1password.com/docs/cli/), then the structure of the - data returned by the `onepassword`, `onepasswordDetailsFields`, and - `onePasswordItemFiles` template functions is different and templates will - need to be updated. + acquired interactively will be passed to the 1Password CLI through a + command line parameter, which is visible to other users of the same system.