feat: knock init and knock.json docs

content/cli.mdx

@@ -132,14 +132,39 @@ The following flags are supported for every command.
 </ContentColumn>
 </Section>
 
+<Section
+  title="Configuring your project"
+  path="/overview/configuring-your-project"
+>
+  <ContentColumn>
+    You can configure your Knock project by creating a `knock.json` file or by using the `knock init` command to generate one for you. This
+    file is a project-level configuration file that tells the Knock CLI where to
+    find your Knock resources.
+
+    For example, if you want to store your Knock resources in the `.knock/` directory, you can create a `knock.json` file with the following content:
+
+{/* prettier-ignore */}
+```json title="Example knock.json file"
+{
+  "knockDir": ".knock/"
+}
+```
+
+    Once you have created the `knock.json` file, all subsequent `knock pull` and `knock push` commands will use the `.knock/` directory as the default target directory relative to the location of the `knock.json` file, regardless of the directory you are currently in.
+
+    If you need to specify a different target directory for a single command, you can use the `--knock-dir` flag, or the `--{resource-type}-dir` flag for specific resource types.
+
+  </ContentColumn>
+</Section>
+
 <Section title="Directory structure" path="/overview/directory-structure">
 <ContentColumn>
 
 There is no required directory structure when working with Knock resources locally. However, if you use the `knock pull` or `knock push` commands, they will produce and expect the directory structure outlined below.
 
 For forward compatibility, we recommend using this structure to ensure your local files work seamlessly with future CLI updates.
 
-When you use `knock pull --knock-dir=./knock`, resources will be grouped by resource type within subdirectories. The following directory structure will be created:
+When you use `knock pull`, resources will be grouped by resource type within subdirectories. The following directory structure will be created:
 
 {/* prettier-ignore */}
 <PreTextDiagram description="Recommended directory structure for Knock resources">
@@ -157,6 +182,31 @@ Each resource type has its own directory structure, which is described in detail
 </ContentColumn>
 </Section>
 
+<Section title="knock init [flags]" path="/init">
+<ContentColumn>
+
+You can initialize a new Knock project with the `init` command. This will create a new `knock.json` file in the current working directory.
+
+### Flags
+
+<Attributes>
+  <Attribute
+    name="--knock-dir"
+    type="directory"
+    description="Optional target directory path to point the Knock CLI to. When not provided, the CLI will prompt you for a directory path."
+  />
+</Attributes>
+
+</ContentColumn>
+<ExampleColumn>
+
+```bash title="Initialize a new Knock project"
+knock init
+```
+
+</ExampleColumn>
+</Section>
+
 <Section title="knock login" path="/login">
 <ContentColumn>
 
@@ -192,7 +242,7 @@ knock logout
 
 Pulls the contents of all Knock resources (workflows, partials, email layouts, translations, guides, and message-types) from Knock into your local file system.
 
-Resources will be grouped by resource type within subdirectories of the target directory path set by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands.
+Resources will be grouped by resource type within subdirectories of the target directory path set either by your `knock.json` file or by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands.
 
 ### Flags
 
@@ -237,7 +287,9 @@ knock pull --knock-dir=./knock
 <Section title="knock push [flags]" path="/push">
 <ContentColumn>
 
-Pushes all local resource files (workflows, partials, email layouts, and translations) back to Knock and upserts them. This command expects the directory structure to be the same as the one created by the `knock pull` command.
+Pushes all local resource files (workflows, partials, email layouts, and translations) back to Knock and upserts them.
+
+Resources will be pushed to the target directory path set either by your `knock.json` file or by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands.
 
 ### Flags
 
@@ -537,6 +589,8 @@ knock workflow get my-workflow --environment=production
 
 You can pull and download workflows with its message templates from Knock to a local file system with the `workflow pull` command. Knock CLI will create a new workflow directory or update the existing workflow directory in the local file system.
 
+By default this command will resolve to the workflows resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--workflows-dir` flag.
+
 Note: if pulling the target workflow for the first time (or all workflows), Knock CLI will ask to confirm before writing to the local file system.
 
 See the [Workflow file structure](/cli/workflow/file-structure) section for details on how workflow files are organized.
@@ -597,6 +651,8 @@ knock workflow pull --all --workflows-dir=./workflows
 
 You can push and upload a workflow directory to Knock with the `workflow push` command. Knock will update an existing workflow by the matching workflow key, or create a new workflow if it does not exist yet.
 
+By default this command will resolve to the workflows resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--workflows-dir` flag.
+
 Note:
 
 - The `workflow push` command only pushes workflows into the `development` environment.
@@ -960,6 +1016,8 @@ knock layout get default --environment=production
 
 Pulls the contents of one or all email layouts from Knock into your local file system. Using `<layout_key>` you can pull a single email layout specified by the key, or use the `--all` flag to pull all email layouts from Knock at once.
 
+By default this command will resolve to the email layouts resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--email-layouts-dir` flag.
+
 See the [Layout file structure](/cli/email-layout/file-structure) section for details on how layout files are organized.
 
 ### Flags
@@ -1004,6 +1062,8 @@ knock layout pull --all
 
 Pushes local email layouts back to Knock and upserts them. Using `<layout_key>` you can push a single email layout specified by the key, or use the `--all` flag to push all email layouts from Knock at once.
 
+By default this command will resolve to the email layouts resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--email-layouts-dir` flag.
+
 See the [Layout file structure](/cli/email-layout/file-structure) section for details on how layout files are organized.
 
 ### Flags
@@ -1207,6 +1267,8 @@ The `<translation_ref>` is a identifier string that refers to a unique translati
 
 When `<translation_ref>` is a locale code and specified with the `--all` flag, all translations for that locale are pulled.
 
+By default this command will resolve to the translations resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--translations-dir` flag.
+
 See the [Translation file structure](/cli/translation/file-structure) section for details on how translation files are organized.
 
 ### Flags
@@ -1274,6 +1336,8 @@ The `<translation_ref>` is a identifier string that refers to a unique translati
 
 When `<translation_ref>` is a locale code and specified with the `--all` flag, all translations for that locale are pushed.
 
+By default this command will resolve to the translations resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--translations-dir` flag.
+
 See the [Translation file structure](/cli/translation/file-structure) section for details on how translation files are organized.
 
 ### Flags
@@ -1478,6 +1542,8 @@ knock partial get my-partial --environment=production
 
 You can pull and download partial files from Knock to a local file system with the `partial pull` command. Knock CLI will create a new partial directory or update the existing partial directory in the local file system.
 
+By default this command will resolve to the partial resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--partials-dir` flag.
+
 Note: if pulling the target partial for the first time (or all partials), Knock CLI will ask to confirm before writing to the local file system.
 
 See the [Partial file structure](/cli/partial/file-structure) section for details on how partial files are organized.
@@ -1534,6 +1600,8 @@ knock partial pull --all
 
 You can push and upload a partial directory to Knock with the `partial push` command. Knock will update an existing partial by the matching partial key, or create a new partial if it does not exist yet.
 
+By default this command will resolve to the partial resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--partials-dir` flag.
+
 Note:
 
 - The `partial push` command only pushes partials into the `development` environment.
@@ -1893,6 +1961,8 @@ knock guide get my-guide --environment=production
 
 You can pull and download guides from Knock to a local file system with the `guide pull` command. Knock CLI will create a new guide directory or update the existing guide directory in the local file system.
 
+By default this command will resolve to the guides resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--guides-dir` flag.
+
 Note: if pulling the target guide for the first time (or all guides), Knock CLI will ask to confirm before writing to the local file system.
 
 See the [Guide file structure](/cli/guide/file-structure) section for details on how guide files are organized.
@@ -1953,6 +2023,8 @@ knock guide pull --all --guides-dir=./guides
 
 You can push and upload a guide directory to Knock with the `guide push` command. Knock will update an existing guide by the matching guide key, or create a new guide if it does not exist yet.
 
+By default this command will resolve to the guides resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--guides-dir` flag.
+
 Note:
 
 - The `guide push` command only pushes guides into the `development` environment.
@@ -2201,6 +2273,8 @@ knock message-type get my-message-type --environment=production
 
 Pull one or more in-app message types from an environment into a local file system. Knock CLI will create a new message type directory or update the existing message type directory in the local file system.
 
+By default this command will resolve to the message types resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--message-types-dir` flag.
+
 Note: if pulling the target message type for the first time (or all message types), Knock CLI will ask to confirm before writing to the local file system.
 
 See the [Message type file structure](/cli/message-type/file-structure) section for details on how message type files are organized.
@@ -2261,6 +2335,8 @@ knock message-type pull --all --message-types-dir=./message-types
 
 Push one or more message types from a local file system to Knock. Knock will update an existing message type by the matching message type key, or create a new message type if it does not exist yet.
 
+By default this command will resolve to the message types resource directory via your `knock.json` file. When not set, will use the current working directory as the default. In the case of the `--all` flag, the target directory path will be resolved via your `knock.json` file or the `--message-types-dir` flag.
+
 Note:
 
 - The `message-type push` command only pushes message types into the `development` environment.

content/developer-tools/knock-cli.mdx

@@ -47,6 +47,18 @@ If you need to authenticate in a remote environment, or want complete control, y
 
 Once you have generated a service token, you can verify it works by running `knock whoami --service-token=YOUR_SERVICE_TOKEN`. If your token is valid and configured properly, you'll receive a 200 response that shows the account name and the service token name.
 
+## Working with a knock.json file
+
+You can configure the Knock CLI for your project by creating a `knock.json` file or by using the `knock init` command to generate one for you. The `knock.json` file is a project-level configuration file that tells the Knock CLI where to find your Knock resources.
+
+```json title="Example knock.json file"
+{
+  "knockDir": "./knock"
+}
+```
+
+Once set, the Knock CLI will use the `knockDir` property for all push and pull commands. If you don't specify a `knockDir` property, or if the property is not set, the Knock CLI will use the current working directory as the default, or you will have to pass in the `--knock-dir` or `--{resource-type}-dir` flags for each command.
+
 ## CLI reference
 
 You can find a complete reference for all of the commands and flags available on the [CLI in our comprehensive reference](/cli/overview).

data/sidebars/cliSidebar.ts

@@ -9,6 +9,7 @@ export const CLI_SIDEBAR: SidebarContent[] = [
       { slug: "/installation", title: "Install the Knock CLI" },
       { slug: "/authentication", title: "Authentication" },
       { slug: "/global-flags", title: "Global flags" },
+      { slug: "/configuring-your-project", title: "Configuring your project" },
       { slug: "/directory-structure", title: "Directory structure" },
     ],
     sidebarMenuDefaultOpen: true,
@@ -24,6 +25,11 @@ export const CLI_SIDEBAR: SidebarContent[] = [
     slug: "/cli/logout",
   },
 
+  {
+    title: "Init",
+    slug: "/cli/init",
+  },
+
   {
     title: "Pull all resources",
     slug: "/cli/pull",

next-env.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
 /// <reference types="next/navigation-types/compat/navigation" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.