Add FAQs or Common issues section in README

[matiasracedo]

When testing the tool, I would get this error in the terminal "zsh: command not found: zitadel-tools" It would be helpful to have a section that describes this error and how to fix it. See proposal below:

❓ FAQ: After installing zitadel-tools with go install, the command is not found

Problem

After running:

go install github.com/zitadel/zitadel-tools@latest

You try to run zitadel-tools, but see:

zsh: command not found: zitadel-tools

---

Solution: Ensure your Go bin directory is in your PATH

1. Confirm the install succeeded

Run the install command and check for errors:

go install github.com/zitadel/zitadel-tools@latest

If there’s an error, installation didn’t complete.

2. Locate the binary

By default, Go installs binaries to your user Go bin directory, typically:

• For Go 1.17 and later: ~/go/bin
• For older versions: $GOPATH/bin (usually also ~/go/bin if not set)

Check if the binary exists:

ls ~/go/bin/zitadel-tools

3. Add Go bin directory to your PATH

If the file exists, but the command is still not found, your Go bin directory is not in your PATH. Add it as follows:

• For Zsh (.zshrc), add:

  export PATH="$PATH:$HOME/go/bin"
  

• For Bash (.bashrc or .bash_profile), add:

  export PATH="$PATH:$HOME/go/bin"
  

After editing your shell configuration, apply the change:

source ~/.zshrc   # or source ~/.bashrc

4. Test the command

Open a new terminal, or run:

zitadel-tools --help

You should now see the help message for the tool.

---

Troubleshooting Checklist

Step	Command	What to Expect
Install	go install github.com/zitadel/zitadel-tools@latest	No error output
Check binary exists	ls ~/go/bin/zitadel-tools	File is listed
Add to PATH	Add export line to .zshrc/.bashrc
Apply config	source ~/.zshrc or source ~/.bashrc	No output
Test command	zitadel-tools --help	Help text is shown

---

If You Still Have Issues

• Double-check for typos: zitadel-tools, not zitadel.

• Ensure you opened a new terminal or sourced your shell configuration.

• Check the output of:

  ls ~/go/bin/
  echo $PATH
  

  The Go bin directory should appear in both.

If the issue persists, please open an issue on the [GitHub repository](https://github.com/zitadel/zitadel-tools/issues) with details and your environment information.

[elinashoko]

Thanks @matiasracedo we'll fix this when we start to revamp the documentation.