github.com/rpdict/ponzu@v0.10.1-0.20190226054626-477f29d6bf5e/docs/src/CLI/General-Usage.md (about) 1 title: Using the Ponzu Command Line Interface (CLI) 2 3 ```bash 4 $ ponzu [flags] command <params> 5 ``` 6 7 ## Commands 8 9 ### new 10 11 Creates a project directory of the name supplied as a parameter immediately 12 following the 'new' option in the $GOPATH/src directory. Note: 'new' depends on 13 the program 'git' and possibly a network connection. If there is no local 14 repository to clone from at the local machine's $GOPATH, 'new' will attempt to 15 clone the 'github.com/rpdict/ponzu' package from over the network. 16 17 Example: 18 ```bash 19 $ ponzu new github.com/nilslice/proj 20 > New ponzu project created at $GOPATH/src/github.com/nilslice/proj 21 ``` 22 --- 23 24 ### generate, gen, g 25 26 Generate boilerplate code for various Ponzu components, such as `content`. 27 28 Example: 29 ```bash 30 generator struct fields and built-in types... 31 | | 32 v v 33 $ ponzu gen content review title:"string" body:"string":richtext rating:"int" 34 ^ ^ 35 | | 36 struct type (optional) input view specifier 37 ``` 38 39 The command above will generate the file `content/review.go` with boilerplate 40 methods, as well as struct definition, and corresponding field tags like: 41 42 ```go 43 type Review struct { 44 item.Item 45 46 Title string `json:"title"` 47 Body string `json:"body"` 48 Rating int `json:"rating"` 49 Tags []string `json:"tags"` 50 } 51 ``` 52 53 The generate command will intelligently parse more sophisticated field names 54 such as 'field_name' and convert it to 'FieldName' and vice versa, only where 55 appropriate as per common Go idioms. Errors will be reported, but successful 56 generate commands return nothing. 57 58 **Input View Specifiers** _(optional)_ 59 60 The CLI can optionally parse a third parameter on the fields provided to generate 61 the type of HTML view an editor field is presented within. If no third parameter 62 is added, a plain text HTML input will be generated. In the example above, the 63 argument shown as `body:string:richtext` would show the Richtext input instead 64 of a plain text HTML input (as shown in the screenshot). The following input 65 view specifiers are implemented: 66 67 | CLI parameter | Generates | 68 |---------------|-----------| 69 | checkbox | [`editor.Checkbox()`](/Form-Fields/HTML-Inputs/#editorcheckbox) | 70 | custom | generates a pre-styled empty div to fill with HTML | 71 | file | [`editor.File()`](/Form-Fields/HTML-Inputs/#editorfile) | 72 | hidden | [`editor.Input()`](/Form-Fields/HTML-Inputs/#editorinput) + uses type=hidden | 73 | input, text | [`editor.Input()`](/Form-Fields/HTML-Inputs/#editorinput) | 74 | richtext | [`editor.Richtext()`](/Form-Fields/HTML-Inputs/#editorrichtext) | 75 | select | [`editor.Select()`](/Form-Fields/HTML-Inputs/#editorselect) | 76 | textarea | [`editor.Textarea()`](/Form-Fields/HTML-Inputs/#editortextarea) | 77 | tags | [`editor.Tags()`](/Form-Fields/HTML-Inputs/#editortags) | 78 79 **Generate Content References** 80 81 It's also possible to generate all of the code needed to create references between 82 your content types. The syntax to do so is below, but refer to the [documentation](/CLI/Generating-References) 83 for more details: 84 85 ```bash 86 $ ponzu gen c author name:string genre:string:select 87 $ ponzu gen c book title:string author:@author,name,genre 88 ``` 89 The commands above will generate a `Book` Content type with a reference to an 90 `Author` item, by also generating a [`reference.Select`](/Form-Fields/HTML-Inputs/#referenceselect) 91 as the view for the `author` field. 92 93 --- 94 95 ### build 96 97 From within your Ponzu project directory, running build will copy and move 98 the necessary files from your workspace into the vendored directory, and 99 will build/compile the project to then be run. 100 101 Optional flags: 102 - `--gocmd` sets the binary used when executing `go build` within `ponzu` build step 103 104 Example: 105 ```bash 106 $ ponzu build 107 (or) 108 $ ponzu build --gocmd=go1.8rc1 # useful for testing 109 ``` 110 111 Errors will be reported, but successful build commands return nothing. 112 113 --- 114 115 ### run 116 117 Starts the HTTP server for the JSON API, Admin System, or both. 118 The segments, separated by a comma, describe which services to start, either 119 'admin' (Admin System / CMS backend) or 'api' (JSON API), and, optionally, 120 if the server should utilize TLS encryption - served over HTTPS, which is 121 automatically managed using Let's Encrypt (https://letsencrypt.org) 122 123 Optional flags: 124 125 - `--bind` sets the address for ponzu to bind the HTTP(S) server 126 - `--port` sets the port on which the server listens for HTTP requests [defaults to 8080] 127 - `--https-port` sets the port on which the server listens for HTTPS requests [defaults to 443] 128 - `--https` enables auto HTTPS management via Let's Encrypt (port is always 443) 129 - `--dev-https` generates self-signed SSL certificates for development-only (port is 10443) 130 - `--docs` runs a local documentation server in case of no network connection 131 - `--docs-port` sets the port on which the docs server listens for HTTP requests [defaults to 1234] 132 133 Example: 134 ```bash 135 $ ponzu run 136 (or) 137 $ ponzu run --bind=0.0.0.0 138 (or) 139 $ ponzu run --port=8080 --https admin,api 140 (or) 141 $ ponzu run admin 142 (or) 143 $ ponzu run --port=8888 api 144 (or) 145 $ ponzu run --dev-https 146 ``` 147 Defaults to `$ ponzu run --port=8080 admin,api` (running Admin & API on port 8080, without TLS) 148 149 *Note:* 150 Admin and API cannot run on separate processes unless you use a copy of the 151 database, since the first process to open it receives a lock. If you intend 152 to run the Admin and API on separate processes, you must call them with the 153 'ponzu' command independently. 154 155 --- 156 157 ### upgrade 158 159 Will backup your own custom project code (like content, addons, uploads, etc) so 160 we can safely re-clone Ponzu from the latest version you have or from the network 161 if necessary. Before running `$ ponzu upgrade`, you should update the `ponzu` 162 package by running `$ go get -u github.com/rpdict/ponzu/...` 163 164 Example: 165 ```bash 166 $ ponzu upgrade 167 ``` 168 169 --- 170 171 ### add, a 172 173 Downloads an addon to GOPATH/src and copies it to the current Ponzu project's 174 `/addons` directory. 175 176 Example: 177 ```bash 178 $ ponzu add github.com/bosssauce/fbscheduler 179 ``` 180 181 Errors will be reported, but successful add commands return nothing. 182 183 --- 184 185 ### version, v 186 187 Prints the version of Ponzu your project is using. Must be called from within a 188 Ponzu project directory. By passing the `--cli` flag, the `version` command will 189 print the version of the Ponzu CLI you have installed. 190 191 Example: 192 ```bash 193 $ ponzu version 194 Ponzu v0.8.2 195 # (or) 196 $ ponzu version --cli 197 Ponzu v0.9.2 198 ``` 199 200 --- 201 202 ## Contributing 203 204 1. Checkout branch ponzu-dev 205 2. Make code changes 206 3. Test changes to ponzu-dev branch 207 - make a commit to ponzu-dev 208 - to manually test, you will need to use a new copy (ponzu new path/to/code), 209 but pass the `--dev` flag so that ponzu generates a new copy from the `ponzu-dev` 210 branch, not master by default (i.e. `$ponzu new --dev /path/to/code`) 211 - build and run with `$ ponzu build` and `$ ponzu run` 212 4. To add back to master: 213 - first push to origin ponzu-dev 214 - create a pull request 215 - will then be merged into master 216 217 _A typical contribution workflow might look like:_ 218 ```bash 219 # clone the repository and checkout ponzu-dev 220 $ git clone https://github.com/rpdict/ponzu path/to/local/ponzu # (or your fork) 221 $ git checkout ponzu-dev 222 223 # install ponzu with go get or from your own local path 224 $ go get github.com/rpdict/ponzu/... 225 # or 226 $ cd /path/to/local/ponzu 227 $ go install ./... 228 229 # edit files, add features, etc 230 $ git add -A 231 $ git commit -m 'edited files, added features, etc' 232 233 # now you need to test the feature.. make a new ponzu project, but pass --dev flag 234 $ ponzu --dev new /path/to/new/project # will create $GOPATH/src/path/to/new/project 235 236 # build & run ponzu from the new project directory 237 $ cd /path/to/new/project 238 $ ponzu build && ponzu run 239 240 # push to your origin:ponzu-dev branch and create a PR at ponzu-cms/ponzu 241 $ git push origin ponzu-dev 242 # ... go to https://github.com/rpdict/ponzu and create a PR 243 ``` 244 245 **Note:** if you intend to work on your own fork and contribute from it, you will 246 need to also pass `--fork=path/to/your/fork` (using OS-standard filepath structure), 247 where `path/to/your/fork` _must_ be within `$GOPATH/src`, and you are working from a branch 248 called `ponzu-dev`. 249 250 For example: 251 ```bash 252 # ($GOPATH/src is implied in the fork path, do not add it yourself) 253 $ ponzu new --dev --fork=github.com/nilslice/ponzu /path/to/new/project 254 ```