breadcrumbs and nav info

Author: davemooreuws

docs/reference/cli.mdx

@@ -0,0 +1,154 @@
+export const description = 'Reference docs for the Nitric CLI'
+
+# Nitric CLI
+
+The Nitric CLI allows you to build, develop, and deploy your serverless application.
+
+To verify your [installation](/getting-started/installation) run `nitric version`. If a version is printed, the CLI is installed correctly.
+
+To get a list of the available commands, run the `nitric help` command and you will see the following:
+
+```text file=<rootDir>/src/assets/cli-usage.txt
+
+```
+
+## Common Commands
+
+There are a few common commands that you will use frequently:
+
+- `nitric new` creates a new project
+- `nitric stack new` creates a new stack within a project
+- `nitric start` runs the Nitric server locally
+- `nitric up` deploys your stack to the cloud
+- `nitric down` destroys your stack from the cloud
+
+## Getting Started
+
+### Projects
+
+To start a new project with nitric, run the `nitric new` command.
+
+```
+nitric new
+```
+
+This will walk through creating the project, including the name and what template you want to start from.
+
+The command will also create a `nitric.yaml` file. This file contains the configuration for your project. The services key is list of globs for your services. The services should point to all services you want to run or deploy.
+
+```yaml
+name: my-project
+services:
+  - match: services/*.ts
+    start: ts-node $SERVICE_PATH
+```
+
+If you want to specify a specific type of service that matches your stack config, you can use this syntax instead:
+
+```yaml
+name: my-project
+services:
+  - match: services/*.ts
+    start: ts-node $SERVICE_PATH
+    type: default
+  - match: custom/*.ts
+    start: ts-node $SERVICE_PATH
+    type: memory-optimized
+```
+
+### Stacks
+
+Creating a new stack will create a configuration for a particular cloud. You can have multiple stacks for one project.
+
+```
+nitric stack new
+```
+
+This will create a `nitric.stackName.yaml` file that contains the configuration for deploying to the cloud. Some providers will have different config, here's an example of an aws stack:
+
+```yaml
+# nitric.my-aws-stack.yaml
+provider: nitric/[email protected]
+region: us-east-1
+```
+
+<Note>The cloud configuration is separate to the cloud credentials.</Note>
+
+<Note>
+  You will still have to set your cloud credentials on your first deployment by
+  following the guide in the cloud's section in the reference documentation.
+</Note>
+
+If you want to specify different configuration for your services you can use the following syntax:
+
+```yaml
+# nitric.my-aws-stack.yaml
+provider: nitric/[email protected]
+region: us-east-1
+telemetry: 10
+config:
+  default:
+    lambda:
+      memory: 1024
+  memory-optimized:
+    lambda:
+      memory: 4096
+```
+
+## Development
+
+When you are ready to test your application and you want to run it locally, you can use the `nitric start` command.
+
+```
+nitric start
+```
+
+This will run the Nitric server for local testing. This will output local endpoints for your apis and open the [local dashboard](/getting-started/local-dashboard) for testing.
+
+For more information on local development, see the [local development](/reference/cli/local-development) docs.
+
+## Deployment
+
+### Deploying the Stack
+
+Once you have tested your application locally and you're ready to deploy, you can do `nitric up`. This command can be optionally supplied with the name of a stack with the `-s` or `--stack` argument. However, the stack will be auto-detected if there is only one or options will be presented if there are multiple. This will set the cloud configuration for that particular deployment.
+
+If this is your first deployment, you will have to set up your cloud credentials before deploying to the cloud. You can find the guides for these in the cloud's section in the reference documentation. The AWS guide is [here](/reference/providers/aws).
+
+```bash
+nitric up
+```
+
+<Note>
+  Each of the cloud provider's deployments take different amounts of time.
+</Note>
+
+### Destroying the Deployment
+
+If you make changes and want to redeploy, you don't have to take the application down, you can just redeploy and it will find the difference. However, if you do want to destroy the application completely, you can use the `nitric down` command.
+
+```
+nitric down
+```
+
+<Note>This will prompt you again before destroying the stack.</Note>
+
+### Listing Stacks
+
+To get information about your stacks, use the `nitric stack list` command.
+
+This will provide give information about its name, its deployment status, when it was last updated, the resource count, and a url to view the deployment on the pulumi console (will require a pulumi account).
+
+## Info
+
+To get information about the CLI version you are using, you can use:
+
+```
+nitric version
+```
+
+For information regarding individual commands, use the `--help` argument on any of the CLI commands. Alternatively you can run:
+
+```
+nitric help
+```

docs/reference/cli/installation.mdx

@@ -0,0 +1,71 @@
+export const description = 'Basic installation instructions for the Nitric CLI'
+
+# CLI Installation
+
+## Prerequisites
+
+Nitric relies on functionality from the following projects to help retrieve plugins, containerize and deploy your application.
+
+Please follow these links to the official installation steps for each.
+
+- [Git](https://git-scm.com/)
+- [Docker](https://docs.docker.com/get-docker/)
+- [Docker Buildx](https://github.com/docker/buildx/)
+- [Pulumi](https://www.pulumi.com/docs/cli/) _(for deployments, only needed if using the default providers)_
+
+<Note>
+  When setting up docker on Linux be sure to follow the [post-installation
+  steps](https://docs.docker.com/engine/install/linux-postinstall/) so you can
+  run docker as a non-root user.
+</Note>
+
+## Installing the Nitric CLI
+
+<CodeGroup>
+
+```bash {{ title: 'macOS' }}
+brew install nitrictech/tap/nitric
+```
+
+```bash {{ title: 'Windows' }}
+scoop bucket add nitric https://github.com/nitrictech/scoop-bucket.git
+scoop install nitric
+```
+
+```bash {{ title: 'Linux' }}
+curl -L https://nitric.io/install?version=latest | bash
+```
+
+</CodeGroup>
+
+### Manual Install
+
+You can download pre-compiled binaries from the [releases](https://github.com/nitrictech/cli/releases) page and copy them into your desired location
+
+## Update to the latest version
+
+<CodeGroup>
+
+```bash {{ title: 'macOS' }}
+brew upgrade nitric
+```
+
+```bash {{ title: 'Windows' }}
+scoop update nitric
+```
+
+```bash {{ title: 'Linux' }}
+curl -L https://nitric.io/install?version=latest | bash
+```
+
+</CodeGroup>
+
+You can easily check which version you're on by running `nitric version`.
+
+## Release notes
+
+You can view the CLI release notes on our [CLI GitHub Releases page](https://github.com/nitrictech/cli/releases).
+
+## What's next
+
+Checkout out our [concepts](/concepts/how-nitric-works) page for a quick overview of Nitric.

docs/reference/cli/local-development.mdx

@@ -0,0 +1,51 @@
+export const description = 'Local development with Nitric'
+
+# Local Development
+
+One of the key features of the Nitric CLI is the ability to run your application locally, using an environment that closely resembles what would be run in the cloud. This allows you to test your application locally before deploying it to the cloud.
+
+Nitric is able to run a local environment that can serve your application, as well as any other services that your application may depend on such as queues, buckets, secrets, etc. This is done by using the `nitric start` command to run your application directly or by using `nitric run` to use Docker to run your application in containers, in both cases any other services that your application may depend on are either hosted by the CLI directly or by using Docker containers.
+
+## Running your application directly
+
+To run your application, you can use the `nitric start` command. This command starts your application and any other services it depends on. This is the recommended way to run your application locally as it is the simplest way to run your application, starts the fastest and makes attaching other tools like debuggers easier.
+
+```bash
+nitric start
+```
+
+Once the command starts, you'll be presented with a list of your running APIs and other services. You'll also see a link to the [local development dashboard](/getting-started/local-dashboard) where you can view a live architecture diagram of your running application and interact with various services for testing.
+
+<img
+  src="/docs/images/docs/dashboard-architecture.png"
+  style={{ maxWidth: 800, width: '100%' }}
+  alt="screen shot of the local development dashboard"
+/>
+
+## Running your application in Containers
+
+If you prefer to run your application in containers, you can use the `nitric run` command. This command builds and runs your application in Docker containers (one per service), along with any other services it depends on. This is useful if you want to run your application in an environment that more closely resembles the cloud, or if you want to run your application in a containerized environment. That said, this method is slower to start and may require more resources than running your application directly, it also makes attaching other tools like debuggers more difficult.
+
+```bash
+nitric run
+```
+
+The output for this command will be similar to the `nitric start` command.
+
+## Stopping your application
+
+In either case you can stop your application by pressing `Esc` or `Ctrl+C` in the terminal where you started your application.
+
+## Enabling Https for local development
+
+By default, Nitric will run your application's APIs and HTTP Proxies over HTTP to avoid common issues with self-signed certificates. In most cases, this is sufficient for local development. However, if you need to test your application over HTTPS, the `nitric start` command supports enabling HTTPS using the `--https-preview` flag.
+
+This command will generate a self-signed certificate and key for your application and use them to serve your application over HTTPS. This is useful if you need to test your application over HTTPS locally, but keep in mind that self-signed certificates are not trusted by browsers and may cause security warnings.
+
+```bash
+nitric start --https-preview
+```
+
+If you need to use a custom certificate and key, you can place them in the `.nitric/tls` directory in your project and Nitric will use them to serve your application over HTTPS. The files must be named `cert.pem` and `key.pem` respectively.
+
+<Note>This feature is experimental and may change in future releases.</Note>