From ebdb466923e55205b1fe36c4631234bfb144e492 Mon Sep 17 00:00:00 2001 From: Corentin Mors Date: Mon, 31 Jul 2023 18:07:00 +0200 Subject: [PATCH] Update install instructions and troubleshooting Fix #124 --- README.md | 58 +++---------------- documentation/pages/_meta.json | 3 +- documentation/pages/install.mdx | 51 +++++++++++++--- .../pages/personal/authentication.mdx | 1 + documentation/pages/troubleshooting.mdx | 49 ++++++++++++++++ 5 files changed, 102 insertions(+), 60 deletions(-) create mode 100644 documentation/pages/troubleshooting.mdx diff --git a/README.md b/README.md index b6adc847..3d859185 100644 --- a/README.md +++ b/README.md @@ -41,13 +41,7 @@ yarn run pkg It outputs in `bundle` directory. Be aware you must use the same Node version as the target. -## How to use - -In order to get help: - -```sh -dcli help -``` +## How to use (read more in our documentation website) In order to sync your vault (this is also the recommended first step): @@ -55,7 +49,7 @@ In order to sync your vault (this is also the recommended first step): dcli sync ``` -In order to **get a password**: +In order to **get a password, secure note or otp**: ```sh dcli p mywebsite @@ -69,33 +63,20 @@ dcli p url=someurl title=mytitle dcli p url,title=mywebsite # will return any entry for which either the url or the title matches mywebsite -``` - -Note: You can select a different output for passwords among `clipboard, password, json`. The JSON option outputs all the matching credentials. -In order to **generate an OTP**: +dcli note [titleFilter] +# will return any secure note for which the title matches titleFilter -```sh dcli otp [filters] +# will return any otp for which the title matches titleFilter ``` -In order to **get a secure note**: - -```sh -dcli note [titleFilter] -``` +Note: You can select a different output for passwords among `clipboard, password, json`. The JSON option outputs all the matching credentials. -### Options +### Debug mode You can use `--debug` to see all the debug logs of the CLI. -In order to disable automatic synchronization of your vault that is done every hour you can use -`dcli configure disable-auto-sync true`. - -If you don't want to use the OS keychain or if you don't want the CLI to save your master password encrypted you can use -`dcli configure save-master-password false`. If you previously had saved your master password encrypted it will delete -it and also delete the local key from the OS keychain. - ## How private data is stored on the computer See [src/crypto/README.md](src/crypto/README.md). @@ -106,28 +87,3 @@ Feel free to contribute to this project, fork and pull request your ideas. Don't include work that is not open source or not from you. **Warranty note**: Dashlane CLI project is provided “as is,” without warranty of any kind, either express or implied. Neither Dashlane, Inc. nor its affiliates, employees or contractors warrant that Dashlane CLI will meet your requirements, operate as required without error or provide future updates. Dashlane, Inc. does not provide customer support on this project. The community is invited to submit bugs and improvements in the issues and pull requests sections of this repository. - -## Troubleshooting - -### Mismatching signatures - -If you are using the CLI in multiple environments, and particularly in an IDE like WebStorm, they may use different -OS keychain environments so the local keys may not match: the reason why signatures are invalid. - -To detect this problem you can, on Linux, install secret-tool: `sudo apt install libsecret-tools`, execute -`secret-tool search service dashlane-cli` on every environment and check if the secrets match. - -If they don't, you can fix the error by manually editing what is stored in the OS keychain using this command: -`secret-tool store --label "dashlane-cli@" service dashlane-cli account ` in the -failing environment with the secret from the healthy environment. - -### RequestError: unable to verify the first certificate - -In NodeJS the list of certificate authorities is hardcoded, read more here: [nodejs/node#4175](https://github.com/nodejs/node/issues/4175). -You can use an environment variable to add custom certs ([see documentation](https://nodejs.org/docs/latest-v16.x/api/cli.html#node_extra_ca_certsfile)): - -```sh -NODE_EXTRA_CA_CERTS=/<...>/.ssl/extra_certs.pem -``` - -See the issue [#46](https://github.com/Dashlane/dashlane-cli/issues/46). diff --git a/documentation/pages/_meta.json b/documentation/pages/_meta.json index cdd9d1a4..51d27284 100644 --- a/documentation/pages/_meta.json +++ b/documentation/pages/_meta.json @@ -3,5 +3,6 @@ "install": "Install", "personal": "Personal", "business": "Business", - "logout": "Logout" + "logout": "Logout", + "troubleshooting": "Troubleshooting" } diff --git a/documentation/pages/install.mdx b/documentation/pages/install.mdx index 2d89acba..a0255de1 100644 --- a/documentation/pages/install.mdx +++ b/documentation/pages/install.mdx @@ -2,9 +2,13 @@ import { Tab, Tabs } from 'nextra-theme-docs' # Install - +The Dashlane CLI can be installed in multiple ways. You can either install it using [Homebrew](https://brew.sh/) on **macOS** and **Linux**, manually with [Yarn](https://yarnpkg.com/) or download the packaged executables for **Windows**, **macOS** and **Linux** on x64 architectures. + + - You can install the Dashlane CLI using [Homebrew](https://brew.sh/), a package manager for macOS. To install Homebrew, run the following command in your terminal: + You can install the Dashlane CLI using [Homebrew](https://brew.sh/), a package manager for __macOS__ and __Linux__. + + To install Homebrew, run the following command in your terminal: ```sh copy /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -15,9 +19,13 @@ import { Tab, Tabs } from 'nextra-theme-docs' ```sh copy brew install dashlane/tap/dashlane-cli ``` + + The CLI is now installed on your machine, it will be updated automatically when a new version is released. - First you need to download or git clone this repository and run the following commands in the root directory of the repository. + This method is available on every environment that supports [Node.js](https://nodejs.org/en/) and Yarn. + + First you need to download or `git clone` this repository and run the following commands in the root directory of the repository. Install the dependencies: @@ -36,19 +44,46 @@ import { Tab, Tabs } from 'nextra-theme-docs' ```sh copy yarn link ``` + + Make sure to pull the latest changes and rebuild the project to get the latest version of the CLI. - Head to the [releases page](https://github.com/Dashlane/dashlane-cli/releases) and download the latest version of the CLI for your platform. + Head to the [releases page](https://github.com/Dashlane/dashlane-cli/releases) and download the latest version of the CLI for your platform (Windows, macOS or Linux). - Move the executable binary to the bin folder of your choice and add it to your PATH. + You may need to mark the binary as executable (on macOS and Linux): - You may need to mark the binary as executable: + ```sh copy + chmod +x dcli-macos-x64 + ``` + + You can now try to run the CLI from the current directory in a terminal (Shell, PowerShell, etc.): ```sh copy - chmod +x dcli-macos + ./dcli-macos-x64 ``` - On macos, you may also need to allow the binary to run in your security settings. To do so, go to System Preferences > Security & Privacy > General and click on "Allow Anyway" next to the message "dcli-macos was blocked from use because it is not from an identified developer". + Move the executable binary to the bin folder of your choice, for instance: + + ```sh + # On macOS: + mv dcli-macos-x64 /usr/local/bin/dcli + + # On Linux: + mv dcli-linux-x64 /usr/local/bin/dcli + + # On Windows: + move dcli-win-x64.exe C:\Windows\System32\dcli.exe + ``` + + On macOS, you may also need to allow the binary to run in your security settings. + To do so, go to `System Preferences > Security & Privacy > General` and click on "Allow Anyway" next to the message "dcli-macos was blocked from use because it is not from an identified developer". + + You will need to get the latest version of the CLI manually by downloading the latest release and replacing the binary in your bin folder. + +## What's next? + +- [Authenticate to your personal account](/personal) +- [Getting Started with Business Commands](/business) diff --git a/documentation/pages/personal/authentication.mdx b/documentation/pages/personal/authentication.mdx index 2b5e287a..1065097b 100644 --- a/documentation/pages/personal/authentication.mdx +++ b/documentation/pages/personal/authentication.mdx @@ -19,6 +19,7 @@ You will be then asked to validate a second factor to register the CLI to your a - Email code validation (default) - TOTP code validation (via an authenticator app) +- Dashlane Authenticator push notification - DUO push notification By completing the device registration process, you'll be now asked to enter your Master Password. diff --git a/documentation/pages/troubleshooting.mdx b/documentation/pages/troubleshooting.mdx new file mode 100644 index 00000000..4b231fbd --- /dev/null +++ b/documentation/pages/troubleshooting.mdx @@ -0,0 +1,49 @@ +import { Tab, Tabs } from 'nextra-theme-docs'; + +# Troubleshooting + +Here are a few common issues and how to fix them. + +### Mismatching signatures + +If you are using the CLI in multiple environments, and particularly in an IDE like WebStorm, they may use different +OS keychain environments so the local keys may not match: the reason why signatures are invalid. + +To detect this problem you can, on Linux, install secret-tool: `sudo apt install libsecret-tools`, execute +`secret-tool search service dashlane-cli` on every environment and check if the secrets match. + +If they don't, you can fix the error by manually editing what is stored in the OS keychain using this command: +`secret-tool store --label "dashlane-cli@" service dashlane-cli account ` in the +failing environment with the secret from the healthy environment. + +### RequestError: unable to verify the first certificate + +In NodeJS the list of certificate authorities is hardcoded, read more here: [nodejs/node#4175](https://github.com/nodejs/node/issues/4175). +You can use an environment variable to add custom certs ([see documentation](https://nodejs.org/docs/latest-v16.x/api/cli.html#node_extra_ca_certsfile)): + + + + + ```sh copy + export NODE_EXTRA_CA_CERTS="/path/to/cert.pem" + ``` + + + + + ```powershell copy + $Env:NODE_EXTRA_CA_CERTS="C:\certs\root.crt" + ``` + + + + + ```batch copy + set NODE_EXTRA_CA_CERTS="C:\certs\root.crt" + ``` + + + + + +See the issue [#46](https://github.com/Dashlane/dashlane-cli/issues/46).