github.com/apex/up@v1.7.1/docs/06-commands.md (about) 1 --- 2 title: Commands 3 slug: commands 4 --- 5 6 7 Up provides the `up` command-line program, used to deploy the app, and manage associated resources such as domains and SSL certificates, as well as operational tasks like viewing logs. 8 9 To view details for a command at any time use `up help`, `up help <command>`, for example `up help team members add`. 10 11 ``` 12 Usage: 13 14 up [<flags>] <command> [<args> ...] 15 16 Flags: 17 18 -h, --help Output usage information. 19 -C, --chdir="." Change working directory. 20 -v, --verbose Enable verbose log output. 21 --format="text" Output formatter. 22 --version Show application version. 23 24 Commands: 25 26 help Show help for a command. 27 build Build zip file. 28 config Show configuration after defaults and validation. 29 deploy Deploy the project. 30 docs Open documentation website in the browser. 31 domains ls List purchased domains. 32 domains check Check availability of a domain. 33 domains buy Purchase a domain. 34 env ls List variables. 35 env add Add a variable. 36 env rm Remove a variable. 37 logs Show log output. 38 metrics Show project metrics. 39 rollback Rollback to a previous deployment. 40 prune Prune old S3 deployments of a stage. 41 run Run a hook. 42 stack plan Plan configuration changes. 43 stack apply Apply configuration changes. 44 stack delete Delete configured resources. 45 stack status Show status of resources. 46 start Start development server. 47 team status Status of your account. 48 team switch Switch active team. 49 team login Sign in to your account. 50 team logout Sign out of your account. 51 team members add Add invites a team member. 52 team members rm Remove a member or invite. 53 team members ls List team members and invites. 54 team subscribe Subscribe to the Pro plan. 55 team unsubscribe Unsubscribe from the Pro plan. 56 team card change Change the default card. 57 team ci Credentials for CI. 58 team add Add a new team. 59 upgrade Install the latest or specified version of Up. 60 url Show, open, or copy a stage endpoint. 61 version Show version. 62 63 Examples: 64 65 Deploy the project to the staging environment. 66 $ up 67 68 Deploy the project to the production stage. 69 $ up deploy production 70 71 Show the staging endpoint url. 72 $ up url 73 74 Tail project logs. 75 $ up logs -f 76 77 Show error or fatal level logs. 78 $ up logs 'error or fatal' 79 80 Run build command manually. 81 $ up run build 82 83 Show help and examples for a command. 84 $ up help team 85 86 Show help and examples for a sub-command. 87 $ up help team members 88 ``` 89 90 ## Deploy 91 92 Deploy the project, by default to the "staging" stage. Note that running `up` and `up deploy` are identical, as it is the default command. 93 94 ``` 95 Usage: 96 97 up deploy [<stage>] 98 99 Flags: 100 101 -h, --help Output usage information. 102 -C, --chdir="." Change working directory. 103 -v, --verbose Enable verbose log output. 104 --format="text" Output formatter. 105 --version Show application version. 106 107 Args: 108 109 [<stage>] Target stage name. 110 ``` 111 112 ### Examples 113 114 Deploy the project to the staging stage. 115 116 ``` 117 $ up 118 ``` 119 120 Deploy the project to the staging stage, this is the same as running `up` without arguments. 121 122 ``` 123 $ up deploy 124 ``` 125 126 Deploy the project to the production stage. 127 128 ``` 129 $ up deploy production 130 ``` 131 132 Note that since `deploy` is the default command the following is also valid: 133 134 ``` 135 $ up production 136 ``` 137 138 ## Config 139 140 Validate and output configuration with defaults applied. 141 142 ``` 143 $ up config 144 ``` 145 146 ```json 147 { 148 "name": "app", 149 "description": "", 150 "type": "server", 151 "headers": null, 152 "redirects": null, 153 "hooks": { 154 "build": "GOOS=linux GOARCH=amd64 go build -o server *.go", 155 "clean": "rm server" 156 }, 157 "environment": null, 158 "regions": [ 159 "us-west-2" 160 ], 161 "inject": null, 162 "lambda": { 163 "role": "arn:aws:iam::ACCOUNT:role/lambda_function", 164 "memory": 128, 165 "timeout": 5 166 }, 167 "cors": null, 168 "error_pages": { 169 "dir": ".", 170 "variables": null 171 }, 172 "proxy": { 173 "command": "./server", 174 "backoff": { 175 "min": 100, 176 "max": 500, 177 "factor": 2, 178 "attempts": 3, 179 "jitter": false 180 } 181 }, 182 "static": { 183 "dir": "." 184 }, 185 "logs": { 186 "disable": false 187 }, 188 "dns": { 189 "zones": null 190 } 191 } 192 ... 193 ``` 194 195 ## Logs 196 197 Show or tail log output with optional query for filtering. When viewing or tailing logs, you are viewing them from _all_ stages, see the examples below to filter on a stage name. 198 199 ``` 200 Usage: 201 202 up logs [<flags>] [<query>] 203 204 Flags: 205 206 -h, --help Output usage information. 207 -C, --chdir="." Change working directory. 208 -v, --verbose Enable verbose log output. 209 --format="text" Output formatter. 210 --version Show application version. 211 -f, --follow Follow or tail the live logs. 212 -S, --since="1d" Show logs since duration (30s, 5m, 2h, 1h30m, 3d, 1M). 213 -e, --expand Show expanded logs. 214 215 Args: 216 217 [<query>] Query pattern for filtering logs. 218 ``` 219 220 ### Expanded output 221 222 Use the `-e` or `--expand` flag to expand log fields: 223 224 ``` 225 $ up -e 'path = "/static/*"' 226 227 1:36:34pm INFO request 228 id: 8ff53267-c33a-11e7-9685-15d48d102ae9 229 ip: 70.66.179.182 230 method: GET 231 path: /static/3.jpg 232 stage: production 233 version: 5 234 235 1:36:34pm INFO response 236 duration: 1ms 237 id: 8ff53267-c33a-11e7-9685-15d48d102ae9 238 ip: 70.66.179.182 239 method: GET 240 path: /static/3.jpg 241 size: 0 B 242 stage: production 243 status: 304 244 version: 5 245 246 1:36:34pm INFO request 247 id: 8ff4bd57-c33a-11e7-bf4b-4f0d97c427c5 248 ip: 70.66.179.182 249 method: GET 250 path: /static/1.png 251 stage: production 252 version: 5 253 ``` 254 255 ### JSON output 256 257 When stdout is not a terminal Up will output the logs as JSON, which can be useful for further processing with tools such as [jq](https://stedolan.github.io/jq/). 258 259 In this contrived example the last 5 hours of production errors are piped to `jq` to produce a CSV of HTTP methods to IP address. 260 261 ``` 262 $ up logs -s 5h 'production error' | jq -r '.|[.fields.method,.fields.ip]|@csv' 263 ``` 264 265 Yielding: 266 267 ``` 268 "GET","207.194.34.24" 269 "GET","207.194.34.24" 270 "GET","207.194.34.24" 271 ``` 272 273 ### Examples 274 275 Show logs from the past day. 276 277 ``` 278 $ up logs 279 ``` 280 281 Show logs from the past 45 minutes. 282 283 ``` 284 $ up -S 45m logs 285 ``` 286 287 Show logs from the past 12 hours. 288 289 ``` 290 $ up -S 12h logs 291 ``` 292 293 Show live log output. 294 295 ``` 296 $ up logs -f 297 ``` 298 299 Show live logs from production only. 300 301 ``` 302 $ up logs -f production 303 ``` 304 305 Show live error logs from production only. 306 307 ``` 308 $ up logs -f 'production error' 309 ``` 310 311 Show error logs, which include 5xx responses. 312 313 ``` 314 $ up logs error 315 ``` 316 317 Show error and warning logs, which include 4xx and 5xx responses. 318 319 ``` 320 $ up logs 'warn or error' 321 ``` 322 323 Show logs with a specific message. 324 325 ``` 326 $ up logs 'message = "user login" method = "GET"' 327 ``` 328 329 Show logs with a specific message with implicit `=`: 330 331 ``` 332 $ up logs '"user login" method = "GET"' 333 ``` 334 335 Show responses with latency above 15ms. 336 337 ``` 338 $ up logs 'duration > 15' 339 ``` 340 341 Show 4xx and 5xx responses in production 342 343 ``` 344 $ up logs 'production (warn or error)' 345 ``` 346 347 Show production 5xx responses with a POST, PUT, or DELETE method. 348 349 ``` 350 $ up logs 'production error method in ("POST", "PUT", "DELETE") 351 ``` 352 353 Show 200 responses with latency above 1500ms. 354 355 ``` 356 $ up logs 'status = 200 duration > 1.5s' 357 ``` 358 359 Show responses with bodies larger than 100kb. 360 361 ``` 362 $ up logs 'size > 100kb' 363 ``` 364 365 Show 4xx and 5xx responses. 366 367 ``` 368 $ up logs 'status >= 400' 369 ``` 370 371 Show emails containing @apex.sh. 372 373 ``` 374 $ up logs 'user.email contains "@apex.sh"' 375 ``` 376 377 Show emails ending with @apex.sh. 378 379 ``` 380 $ up logs 'user.email = "*@apex.sh"' 381 ``` 382 383 Show emails starting with tj@. 384 385 ``` 386 $ up logs 'user.email = "tj@*"' 387 ``` 388 389 Show logs with a more complex query. 390 391 ``` 392 $ up logs 'method in ("POST", "PUT") ip = "207.*" status = 200 duration >= 50' 393 ``` 394 395 ## URL 396 397 Show, open, or copy a stage endpoint. 398 399 ``` 400 Usage: 401 402 up url [<flags>] 403 404 Flags: 405 406 -h, --help Output usage information. 407 -C, --chdir="." Change working directory. 408 -v, --verbose Enable verbose log output. 409 --format="text" Output formatter. 410 --version Show application version. 411 -s, --stage="staging" Target stage name. 412 -o, --open Open endpoint in the browser. 413 -c, --copy Copy endpoint to the clipboard. 414 ``` 415 416 ### Examples 417 418 Show the staging endpoint. 419 420 ``` 421 $ up url 422 ``` 423 424 Open the staging endpoint in the browser. 425 426 ``` 427 $ up url --open 428 ``` 429 430 Copy the staging endpoint to the clipboard. 431 432 ``` 433 $ up url --copy 434 ``` 435 436 Show the production endpoint. 437 438 ``` 439 $ up url -s production 440 ``` 441 442 Open the production endpoint in the browser. 443 444 ``` 445 $ up url -o -s production 446 ``` 447 448 Copy the production endpoint to the clipboard. 449 450 ``` 451 $ up url -c -s production 452 ``` 453 454 ## Metrics 455 456 Show project metrics and estimated cost breakdown for requests, invocation count and the time spent for Lambda invocations. 457 458 ``` 459 Usage: 460 461 up metrics [<flags>] 462 463 Flags: 464 465 -h, --help Output usage information. 466 -C, --chdir="." Change working directory. 467 -v, --verbose Enable verbose log output. 468 --format="text" Output formatter. 469 --version Show application version. 470 -s, --stage="staging" Target stage name. 471 -S, --since="1M" Show metrics since duration (30s, 5m, 2h, 1h30m, 3d, 1M). 472 ``` 473 474 For example: 475 476 ``` 477 $ up metrics -s production -S 15d 478 479 Requests: 13,653 ($0.01) 480 Duration min: 0ms 481 Duration avg: 48ms 482 Duration max: 15329ms 483 Duration sum: 3m6.611s ($0.00) 484 Errors 4xx: 1,203 485 Errors 5xx: 2 486 Invocations: 12,787 ($0.00) 487 Errors: 0 488 Throttles: 0 489 ``` 490 491 ## Start 492 493 Start development server. The development server runs the same proxy that is used in production for serving, so you can test a static site or application locally with the same feature-set. 494 495 See [Stage Overrides](https://up.docs.apex.sh/#configuration.stage_overrides) for an example of overriding the proxy command per-stage, especially useful in development. 496 497 Up Pro supports environment variables, and these will be loaded with `up start`, and variables mapped to the "development" stage will take precedence. For example: 498 499 ``` 500 $ up env set NAME Tobi 501 $ up start # app has NAME available as Tobi 502 503 $ up env set NAME Loki -s development 504 $ up start # app has NAME available Loki 505 ``` 506 507 The `UP_STAGE` and `NODE_ENV` environment variables will be set to "development" automatically. 508 509 ``` 510 Usage: 511 512 up start [<flags>] 513 514 Flags: 515 516 -h, --help Output usage information. 517 -C, --chdir="." Change working directory. 518 -v, --verbose Enable verbose log output. 519 --format="text" Output formatter. 520 --version Show application version. 521 -c, --command=COMMAND Proxy command override 522 -o, --open Open endpoint in the browser. 523 --address=":3000" Address for server. 524 ``` 525 526 ### Examples 527 528 Start development server on port 3000. 529 530 ``` 531 $ up start 532 ``` 533 534 Start development server on port 5000. 535 536 ``` 537 $ up start --address :5000 538 ``` 539 540 Override proxy command. Note that the server created must listen on `PORT`, which is why `--port $PORT` is required for the [gin](https://github.com/codegangsta/gin) example. 541 542 ``` 543 $ up start -c 'go run main.go' 544 $ up start -c 'gin --port $PORT' 545 $ up start -c 'node --some-flag app.js' 546 $ up start -c 'parcel' 547 ``` 548 549 ## Domains 550 551 Manage domain names, and purchase them from AWS Route53 as the registrar. 552 553 ``` 554 Usage: 555 556 up domains <command> [<args> ...] 557 558 Flags: 559 560 -h, --help Output usage information. 561 -C, --chdir="." Change working directory. 562 -v, --verbose Enable verbose log output. 563 --version Show application version. 564 565 Subcommands: 566 567 domains list List purchased domains. 568 domains check Check availability of a domain. 569 domains buy Purchase a domain. 570 571 ``` 572 573 ### Examples 574 575 List purchased domains. 576 577 ``` 578 $ up domains 579 ``` 580 581 Check availability of a domain. 582 583 ``` 584 $ up domains check example.com 585 ``` 586 587 Purchase a domain (with interactive form). 588 589 ``` 590 $ up domains buy 591 ``` 592 593 ## Stack 594 595 Stack resource management. The stack is essentially all of the resources powering your app, which is configured by Up on the first deploy. 596 597 At any time if you'd like to delete the application simply run `$ up stack delete`. To view the status and potential errors use `$ up stack`. 598 599 ``` 600 Usage: 601 602 up stack <command> [<args> ...] 603 604 Flags: 605 606 -h, --help Output usage information. 607 -C, --chdir="." Change working directory. 608 -v, --verbose Enable verbose log output. 609 --version Show application version. 610 611 Subcommands: 612 613 stack plan Plan configuration changes. 614 stack apply Apply configuration changes. 615 stack delete Delete configured resources. 616 stack status Show status of resources. 617 ``` 618 619 ### Examples 620 621 Show status of the stack resources and nameservers. 622 623 ``` 624 $ up stack 625 ``` 626 627 Show resource changes. 628 629 ``` 630 $ up stack plan 631 ``` 632 633 Apply resource changes. 634 635 ``` 636 $ up stack apply 637 ``` 638 639 Delete the stack resources. 640 641 ``` 642 $ up stack delete 643 ``` 644 645 646 ## Build 647 648 Build zip file, typically only helpful for inspecting its contents. If you're interested in seeing what files are causing bloat, use the `--size` flag to list files by size descending. 649 650 ``` 651 Usage: 652 653 up build [<flags>] 654 655 Flags: 656 657 -h, --help Output usage information. 658 -C, --chdir="." Change working directory. 659 -v, --verbose Enable verbose log output. 660 --format="text" Output formatter. 661 --version Show application version. 662 -s, --stage="staging" Target stage name. 663 --size Show zip contents size information. 664 ``` 665 666 ### Examples 667 668 Build archive and save to ./out.zip 669 670 ``` 671 $ up build 672 ``` 673 674 Build archive and output to file via stdout. 675 676 ``` 677 $ up build > /tmp/out.zip 678 ``` 679 680 Build archive list files by size. 681 682 ``` 683 $ up build --size 684 ``` 685 686 Build archive and list size without creating out.zip. 687 688 ``` 689 $ up build --size > /dev/null 690 ``` 691 692 ## Team 693 694 Manage team members, plans, and billing. 695 696 ``` 697 Usage: 698 699 up team <command> [<args> ...] 700 701 Flags: 702 703 -h, --help Output usage information. 704 -C, --chdir="." Change working directory. 705 -v, --verbose Enable verbose log output. 706 --format="text" Output formatter. 707 --version Show application version. 708 709 Subcommands: 710 711 team status Status of your account. 712 team switch Switch active team. 713 team login Sign in to your account. 714 team logout Sign out of your account. 715 team members add Add invites a team member. 716 team members rm Remove a member or invite. 717 team members ls List team members and invites. 718 team subscribe Subscribe to the Pro plan. 719 team unsubscribe Unsubscribe from the Pro plan. 720 team card change Change the default card. 721 team ci Credentials for CI. 722 team add Add a new team. 723 ``` 724 725 ### Examples 726 727 Show active team and subscription status. 728 729 ``` 730 $ up team 731 ``` 732 733 Switch teams interactively. 734 735 ``` 736 $ up team switch 737 ``` 738 739 Sign in or create account with interactive prompt. 740 741 ``` 742 $ up team login 743 ``` 744 745 Sign in to a team. 746 747 ``` 748 $ up team login --email tj@example.com --team apex-software 749 ``` 750 751 Add a new team and automatically switch to the team. 752 753 ``` 754 $ up team add "Apex Software" 755 ``` 756 757 Subscribe to the Pro plan. 758 759 ``` 760 $ up team subscribe 761 ``` 762 763 Invite a team member to your active team. 764 765 ``` 766 $ up team members add asya@example.com 767 ``` 768 769 ## Upgrade 770 771 Install the latest or specified version of Up. The OSS and Pro versions have independent semver, as bugfixes and features for one may not be relevant to the other. 772 773 If you're an Up Pro subscriber, `up upgrade` will _always_ install Up Pro, even when `--target` is specified, there is no need to specify that you want the Pro version. 774 775 ``` 776 Usage: 777 778 up upgrade [<flags>] 779 780 Flags: 781 782 -h, --help Output usage information. 783 -C, --chdir="." Change working directory. 784 -v, --verbose Enable verbose log output. 785 --format="text" Output formatter. 786 --version Show application version. 787 -t, --target=TARGET Target version for upgrade. 788 ``` 789 790 ### Examples 791 792 Upgrade to the latest version available. 793 794 ``` 795 $ up upgrade 796 ``` 797 798 Upgrade to the specified version. 799 800 ``` 801 $ up upgrade -t 0.4.4 802 ``` 803 804 805 ## Prune 806 807 Prune old S3 deployments of a stage. 808 809 ``` 810 Usage: 811 812 up prune [<flags>] 813 814 Flags: 815 816 -h, --help Output usage information. 817 -C, --chdir="." Change working directory. 818 -v, --verbose Enable verbose log output. 819 --format="text" Output formatter. 820 --version Show application version. 821 -s, --stage="staging" Target stage name. 822 -r, --retain=30 Number of versions to retain. 823 ``` 824 825 ### Examples 826 827 Prune and retain the most recent 30 staging versions. 828 829 ``` 830 $ up prune 831 ``` 832 833 Prune and retain the most recent 30 production versions. 834 835 ``` 836 $ up prune -s production 837 ``` 838 839 Prune and retain the most recent 15 production versions. 840 841 ``` 842 $ up prune -s production -r 15 843 ```