From 81792b4fe74bba76aabb160c1db59726df546422 Mon Sep 17 00:00:00 2001
From: Jack Hamer <jackhamer0990@gmail.com>
Date: Fri, 23 Feb 2024 00:25:54 +0200
Subject: [PATCH] chore: add troubleshooting guide and table of contents

---
 README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/README.md b/README.md
index 59038d05..63542ae9 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,24 @@ This CLI tool simplifies the process of developing applications and interacting
 
 </div>
 
+## Table of Contents
+
+- [Prerequisites](#-prerequisites)
+- [Usage](#-usage)
+- [Commands List](#-commands)
+  - [Local Development](#local-development-commands)
+  - [Create Project](#create-project-commands)
+  - [Contract Interaction](#contract-interaction-commands)
+  - [Transaction](#transaction-commands)
+  - [Wallet](#wallet-commands)
+  - [Bridge](#bridge-commands)
+  - [Other Commands](#other-commands)
+- [Supported Chains](#-supported-chains)
+- [Developing New Features](#-developing-new-features)
+- [Official Links](#-official-links)
+- [License](#-license)
+- [Troubleshooting](#-troubleshooting)
+
 ## 🛠 Prerequisites
 
 - [Node.js v18 or higher](https://nodejs.org/en)
@@ -103,3 +121,51 @@ In the meantime, you can test the code manually by running the code in [developm
 ## 📜 License
 
 This project is licensed under [MIT](./LICENSE-MIT).
+
+## ❓ Troubleshooting
+
+Encountering issues with zkSync CLI? Below are some common problems with step-by-step recommendations for resolving them:
+
+<details>
+<summary><b>`unknown command` Error</b></summary>
+
+If you encounter an `unknown command` error, follow these steps:
+
+a. **Check the zkSync CLI Version**
+   - Run `npx zksync-cli --version` to check your current version.
+   - Compare it with the latest version available on [npm](https://www.npmjs.com/package/zksync-cli).
+   - If your version is lower than the one on npm follow the steps bellow. If your version is up-to-date, it's possible that the command was moved or renamed. Use `npx zksync-cli help` for a list of current commands or refer to the documentation.
+
+b. **Verify Local Installation**
+   - Use `npm list zksync-cli` to check if `zksync-cli` is installed in the current directory or any parent directories from where you are running your terminal.
+   - If it is indeed installed, make sure to uninstall it by running `npm uninstall zksync-cli` in its installation location. Remove all instances of `zksync-cli` until there are no more found by `npm list zksync-cli`.
+
+c. **Verify Global Installation**
+   - Use `npm list -g zksync-cli` to check if `zksync-cli` is installed globally.
+   - If it is installed globally, uninstall it using `npm uninstall -g zksync-cli`.
+
+d. **Clean npm Cache**
+   - Run `npm cache clean --force`.
+
+e. **Use the Latest Version**
+   - As a quick fix, or if the above steps don't resolve the issue, use `npx zksync-cli@latest [command]`, for example, `npx zksync-cli@latest dev start`.
+</details>
+
+<details>
+<summary><b>My Version is Outdated</b></summary>
+
+If `npx zksync-cli` is not running the latest version:
+
+- Refer to the guide above to check and update your zkSync CLI version.
+</details>
+
+<details>
+<summary><b>`command not found: npx` Error</b></summary>
+
+If you receive a `command not found: npx` error, it means Node.js is not installed or not correctly set up on your system:
+
+- Install Node.js from [https://nodejs.org/](https://nodejs.org/). This will also install `npm` and `npx`.
+- After installation, restart your terminal and try running `npx zksync-cli` again.
+</details>
+
+For all other issues, we encourage you to ask for help or report them in our [GitHub Discussions](https://github.com/zkSync-Community-Hub/zksync-developers/discussions/new?category=general&title=[zksync-cli]%20<Title>).