wip-cli-doc

docs/cli.md

@@ -0,0 +1,60 @@
+# Puya TS Cli
+
+## Installation
+
+### Puya-TS
+
+Puya-TS can be installed from npm using the command
+
+```shell
+npm i @algorandfoundation/puya-ts [-g]
+```
+
+If installed globally (`-g`) it should be available on your PATH anywhere, otherwise you may need to use `npx puya-ts` to run it, or create an npm script.
+
+```json
+{
+  "scripts": {
+    "build": "puya-ts ..."
+  }
+}
+```
+
+IDEs such as Webstorm automatically add the local `node_modules/.bin` directory to the PATH of the built-in terminal window, meaning `puya-ts ...` should work without `npx` in that window.
+
+You can very a successful installation by running the command with no args
+
+```shell
+> puya-ts
+usage: puya-ts [-h] [--version] {build} ...
+
+positional arguments:
+  ...
+```
+
+### Puya
+
+Puya-ts is only the front end component of the compiler. After parsing and converting TypeScript into a common AST known as AWST, the remainder of the compilation is passed onto the Puya backend compiler. The Puya compiler is written in Python and can be installed using `pipx`. You will require Python 3.12+ and to have pipx available on your path for the following to work.
+
+```shell
+pipx install puyapy
+```
+
+You can verify a successful installation by running the `puya` command with no args.
+
+```shell
+> puya
+usage: puya [-h] [--version] [--log-level {notset,debug,info,warning,error,critical}] [--log-format {default,json}] --options OPTIONS --awst AWST [--source-annotations SOURCE_ANNOTATIONS]
+puya: error: the following arguments are required: --options, --awst
+```
+
+
+## Commands
+
+### Version
+
+Shows the currently installed version of puya-ts, and its targeted puya version.
+
+```shell
+puya-ts --version
+```