# `ggt` Reference 

`ggt` is Gadget's command line interface (CLI) that allows developers to build locally and sync any changes with their Gadget environment. This enables developers to use their preferred text editor and source control system to develop applications.

`ggt` only works with development environments.

## Install `ggt` 

Install `ggt` globally by running:

```sh
npm install -g ggt
```

### Update `ggt` 

When there is a new release of `ggt`, running `ggt` will show you a message letting you know that an update is available. Update it by running:

```sh
npm install -g ggt@latest
```

## Usage 

```sh-session
ggt [COMMAND]
```

##### List of `ggt` commands 

**Application development**

*   `dev` Start local development of your application.
*   `debugger` Configure your editor for backend debugging.
*   `logs` Stream logs from your app in real time.
*   `problems` Show any problems (errors, warnings) in your Gadget application.
*   `eval` Evaluate a JavaScript snippet against your app's API client.
*   `deploy` Deploy your environment to production.

**File management**

*   `status` Show your local and hosted environment file changes.
*   `push` Push your local files to the hosted environment.
*   `pull` Pull your hosted environment files to your local computer.

**Environment variable management**

*   `var` Manage environment variables for your application.

**Utilities**

*   `model` Add and manage models in your app.
*   `action` Add and manage actions in your app.
*   `add` Add models, fields, actions, and routes to your app.
*   `env` Manage environments for your application.
*   `configure` Manage default `ggt` configuration.
*   `completion` Generate shell completion scripts for bash, zsh, and fish.
*   `open` Open Gadget in your default browser.
*   `list` List your available applications.
*   `agent-plugin` Install `AGENTS.md` and Gadget agent skills for your coding agent.

**Account management**

*   `login` Log in to your account.
*   `logout` Log out of your account.
*   `whoami` Print the currently logged-in account.

**Information**

*   `version` Print this version of `ggt`.

##### Global options 

###### `-h` `--help`  

Show command help.

*   `-h` shows a compact summary.
*   `--help` shows expanded descriptions, flag details, and examples.

You can also run `ggt help [command]`.

###### `-v` `--verbose` 

Print verbose output.

###### `--json` 

Print output as JSON.

###### `--version` 

Print the current `ggt` version and exit.

## Commands 

### **`ggt dev`** 

Clones your hosted Gadget environment's file directory to your local machine, allowing for local development using your favorite code editor and source control support.

`ggt dev` will run until stopped. While running, any changes made locally will be pushed to the hosted environment, and any changes made in the hosted environment will be pulled down locally.

If your app's local directory already exists, this command first syncs local and environment directories to ensure they match. Changes are tracked from the last sync run (`ggt dev`, `ggt push`, `ggt pull`). If there are conflicts, you will be asked to resolve them before starting development.

Only one `ggt dev` process can run per directory at a time. If you try to start `ggt dev` in a directory where it is already running, ggt will print the PID of the existing process and exit.

Gadget only supports [Yarn v1](https://classic.yarnpkg.com/lang/en/) for dependency management during synchronization.

Avoid deleting or moving all your files while `ggt dev` is active! Gadget will also delete all of your hosted files which will lead to a fatal error in your hosted environment.

##### Usage 

```sh-session
ggt dev [DIRECTORY] [--app <app_name>] [options]
```

##### Example 

Clone the `my-blog` app into `./my-blog` and keep it up to date with the development environment:

```sh
ggt dev ./my-blog --app my-blog --env development
```

##### Arguments 

###### `DIRECTORY` 

The directory to sync files to.

Defaults to "." (current directory).

##### Options 

###### `-a` `--app <app_name>` 

Selects the app to sync files with.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt dev --app my-blog
```

###### `-e` `--env <env_name>` 

Selects the environment to sync files with.

If not specified, defaults to the environment set in `.gadget/sync.json`.

```sh
ggt dev --env development
```

###### `--prefer <filesystem>` 

Sets the preferred source, **local** or **environment**, in the event of conflicting changes.

If not specified, `ggt` prompts you to manually select during conflicts.

```sh
ggt dev --prefer local
```

###### `--allow <flag,...>` 

Enables specific `--allow-*` flags using a comma-separated shorthand. Passing `all` as a value enables all flags, equivalent to `--allow-all`. If an unknown value is passed, `ggt` suggests the closest valid match.

Valid values are `unknown-directory` and `different-app`.

```sh
ggt dev --allow=unknown-directory,different-app
```

###### `--allow-all` 

Enables all `--allow-*` flags at once.

```sh
ggt dev --allow-all
```

###### `--allow-unknown-directory` 

Syncs to any local directory with existing files, even if the `.gadget/sync.json` file is missing.

```sh
ggt dev --allow-unknown-directory
```

###### `--allow-different-app` 

Syncs with a different app using the `--app` command, instead of the one specified in the `.gadget/sync.json` file.

```sh
ggt dev --app task-manager --allow-different-app
```

#### Ignore files 

`ggt dev` uses a `.ignore` file to skip over certain files and folders during the sync process. Place files in the `.ignore` folder to specify what should be left out.

The `.ignore` file follows the same [rules](https://git-scm.com/docs/gitignore) as `.gitignore` and wildcard patterns are supported.

These files are always ignored:

*   `node_modules`
*   `.gadget`
*   `.git`
*   `.DS_STORE`

### **`ggt debugger`** 

Configures your editor for debugging Gadget app's backend. This command sets up the necessary launch and task configurations in your editor to enable debugging.

After configuration, you can start debugging by using the **Gadget debugger** launch configuration from your editor.

`ggt debugger` runs a fully compliant [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) proxy for the Node process powering your Gadget backend. Any client that can speak CDP can connect to the `localhost` address that `ggt debugger` sets up, `localhost:9229` by default.

##### Usage 

```sh-session
ggt debugger [--configure <editor>]
```

##### Example 

Configure VS Code for debugging:

```sh
ggt debugger --configure vscode
```

##### Options 

###### `--configure <editor>` 

Selects the editor to configure for debugging. This flag only needs to be run once per project.

Must be one of the following:

*   **vscode** Configures VS Code or its forks for debugging.
*   **cursor** Configures Cursor for debugging.

`ggt debugger --configure vscode` and `ggt debugger --configure cursor` set up VS Code's Debug Adapter to connect to the `ggt debugger` process and runs that process in the background.

This option adds configuration files to your project:

*   `.vscode/launch.json` - Launch configuration for starting the debugger.
*   `.vscode/tasks.json` - Task configuration for debugger tasks.

`ggt debugger --configure` will fail if you already have `.vscode/tasks.json` or `.vscode/launch.json` files in your project. You'll need to remove or rename these files before running the configuration command, then manually merge existing configuration.

### **`ggt logs`** 

Prints recent logs from your app and exits.

By default, `ggt logs` fetches logs from the last 5 minutes and exits. This makes it suitable for scripting, one-off inspection, and agent-driven debugging. To stream logs continuously, use the `--follow` flag.

This includes HTTP requests, background action invocations, and console output from your environment.

`ggt log` is accepted as an alias for `ggt logs`.

##### Usage 

```sh-session
ggt logs [options]
```

##### Examples 

Print recent logs for the app in `.gadget/sync.json`:

```sh
$ ggt logs
```

Stream logs continuously:

```sh
$ ggt logs --follow
```

Print logs from a specific point in time:

```sh
$ ggt logs --start 2026-03-12T10:00:00Z
```

Print logs from production:

```sh
$ ggt logs --env production
```

Show only logs emitted by your code at `warn` level or above:

```sh
$ ggt logs --my-logs --log-level warn
```

Output logs as JSON:

```sh
$ ggt logs --json
```

##### Options 

###### `-f` `--follow` 

Streams logs continuously instead of printing recent logs and exiting.

```sh
ggt logs --follow
```

###### `--start <datetime>` 

Sets the start time for the log query as an ISO 8601 datetime. Defaults to 5 minutes ago.

Cannot be combined with `--follow`.

```sh
ggt logs --start 2026-03-12T10:00:00Z
```

###### `-a` `--app <app_name>` 

Selects the application whose logs you want to view.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt logs --app my-blog
```

###### `-e` `--env <env_name>` 

Selects the environment whose logs you want to view.

If not specified, defaults to the environment set in `.gadget/sync.json`.

```sh
ggt logs --env staging
```

###### `-l` `--log-level <level>` 

Sets the minimum log level to display.

Valid values are `trace`, `debug`, `info`, `warn`, and `error`.

```sh
ggt logs --log-level debug
```

###### `-m` `--my-logs` 

Shows only logs emitted by your code.

This filters out built-in platform logs.

```sh
ggt logs --my-logs
```

### **`ggt problems`** 

Shows any problems (errors, warnings) found in your Gadget application without deploying.

Issues can include TypeScript errors, Gelly errors, and development keys in use. If the command finds no issues, it prints `No problems found.`

`ggt problem` is accepted as an alias for `ggt problems`.

##### Usage 

```sh-session
ggt problems [options]
```

##### Examples 

Check the app set in `.gadget/sync.json`:

```sh
$ ggt problems
```

Check a specific app and environment:

```sh
$ ggt problems --app my-blog --env development
```

##### Options 

###### `-a` `--app <app_name>` 

Selects the app to check for problems.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt problems --app my-blog
```

###### `-e` `--env <env_name>` 

Selects the environment to check for problems.

If not specified, defaults to the environment set in `.gadget/sync.json`.

```sh
ggt problems --env development
```

### **`ggt eval`** 

Evaluates a JavaScript snippet against your Gadget app's API client.

The snippet receives an `api` variable: a pre-constructed Gadget API client authenticated as the developer. Results are formatted like Node.js REPL output.

Write operations are disallowed by default. Use `--allow-writes` to enable them.

##### Usage 

```sh-session
ggt eval [options] <snippet>
```

##### Examples 

Fetch all users from your app:

```sh
$ ggt eval 'api.user.findMany()'
```

Run against a specific app and environment:

```sh
$ ggt eval --app my-app --env staging 'api.user.findFirst()'
```

Run a write operation:

```sh
$ ggt eval --allow-writes 'api.user.delete("123")'
```

##### Arguments 

###### `<snippet>` 

A JavaScript expression or statement to evaluate. The snippet has access to an `api` variable: the Gadget API client for your app.

If the snippet is a statement rather than an expression, an implicit `return` is added automatically.

##### Options 

###### `-a` `--app <app_name>` 

Selects the app whose API client the snippet runs against.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt eval --app my-blog 'api.user.findMany()'
```

###### `-e` `--env <env_name>` 

Selects the environment whose API client the snippet runs against.

If not specified, defaults to the environment set in `.gadget/sync.json`.

```sh
ggt eval --env dev-2 'api.user.findMany()'
```

###### `-w` `--allow-writes` 

Allows write operations in the snippet. By default, the API client is read-only.

```sh
ggt eval --allow-writes 'api.user.delete("123")'
```

###### `--allow <flag,...>` 

Enables specific `--allow-*` flags using a comma-separated shorthand. Passing `all` as a value enables all flags, equivalent to `--allow-all`. If an unknown value is passed, `ggt` suggests the closest valid match.

Valid values are `writes`.

```sh
ggt eval --allow=writes 'api.user.delete("123")'
```

###### `--allow-all` 

Enables all `--allow-*` flags at once.

```sh
ggt eval --allow-all 'api.user.delete("123")'
```

###### `--json` 

Outputs the result as JSON instead of Node.js inspect format.

```sh
ggt eval --json 'api.user.findMany()'
```

### **`ggt deploy`** 

Deploys your application to production.

It first syncs local and hosted environment directories to ensure they match. Changes are tracked from the last sync run (`ggt dev`, `ggt push`, `ggt deploy`). If there are conflicts, you will be asked to resolve them before deploying.

##### Usage 

```sh-session
ggt deploy [options]
```

##### Examples 

Deploy from `staging` environment for `my-blog` app to production:

```sh
$ ggt deploy --app my-blog --from staging
```

Deploy and skip all interactive prompts:

```sh
$ ggt deploy --force --allow-all
```

Deploy and skip specific interactive prompts:

```sh
$ ggt deploy --force --allow=problems
```

##### Options 

###### `-a` `--app <app_name>` 

Selects the app to deploy to production.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt deploy --app my-blog
```

###### `-e` `--env` `--from <env_name>` 

Selects the environment to deploy to production.

If not specified, defaults to the environment set in `.gadget/sync.json`.

```sh
ggt deploy --from development
```

###### `-f` `--force` 

Forces deploy by discarding any changes made to the environment directory since the last sync.

Defaults to `false`.

```sh-session
ggt deploy --force
```

###### `--allow <flag,...>` 

Enables specific `--allow-*` flags using a comma-separated shorthand. Passing `all` as a value enables all flags, equivalent to `--allow-all`. If an unknown value is passed, `ggt` suggests the closest valid match. Use this in CI/CD pipelines instead of spelling out each flag individually.

Valid values are `problems`, `charges`, `data-delete`, `unknown-directory`, and `different-app`.

```sh
ggt deploy --force --allow=problems,charges,data-delete
```

###### `--allow-all` 

Enables all `--allow-*` flags at once. Use this in CI/CD pipelines to skip all interactive prompts without listing each flag individually.

```sh
ggt deploy --force --allow-all
```

###### `--allow-problems` `--allow-issues` 

Proceeds with deployment despite any existing issues.

Issues can be found in the Gadget editor's problems drawer, and some examples include Gelly errors, the use of development keys, and Typescript errors.

Defaults to `false`.

```sh
ggt deploy --allow-problems
```

###### `--allow-charges` 

Allows the app to deploy even if it results in additional charges to your plan.

Defaults to `false`.

```sh
ggt deploy --allow-charges
```

###### `--allow-data-delete` 

Allows the app to deploy even if removed models or fields will permanently delete production data.

Defaults to `false`.

```sh
ggt deploy --allow-data-delete
```

###### `--allow-unknown-directory` 

Deploys a different app using the `--app` command, instead of the one specified in the `.gadget/sync.json` file.

```sh
ggt deploy --allow-unknown-directory
```

###### `--allow-different-app` 

Deploys a different app using the `--app` command, instead of the one specified in the “.gadget/sync.json” file.

```sh
ggt deploy --allow-different-app
```

### **`ggt status`** 

Shows whether `ggt dev` is currently running and the file changes between local and hosted environments since the last sync (`ggt dev`, `ggt push`, `ggt pull`).

##### Usage 

```sh-session
ggt status
```

### **`ggt push`** 

Push your local files to your environment directory.

This command tracks changes in your environment directory since the last sync (`ggt dev`, `ggt push`, `ggt pull`). If changes are detected, you will be prompted to discard them or abort the push.

##### Usage 

```sh-session
ggt push [options]
```

##### Examples 

Push all local changes to the `main` environment by discarding any changes made on `main`:

```sh
ggt push --env main --force
```

Push and skip all interactive prompts:

```sh
ggt push --force --allow-all
```

##### Options 

###### `-a` `--app <app_name>` 

Selects the app to push your local changes to.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt push --app my-blog
```

###### `-e` `--env <env_name>` 

Selects the environment to push local changes to.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt push --env staging
```

###### `-f` `--force` 

Forces a push by discarding any changes made on your hosted environment directory since the last sync.

```sh
ggt push --force
```

###### `--allow <flag,...>` 

Enables specific `--allow-*` flags using a comma-separated shorthand. Passing `all` as a value enables all flags, equivalent to `--allow-all`. If an unknown value is passed, `ggt` suggests the closest valid match.

Valid values are `unknown-directory` and `different-app`.

```sh
ggt push --allow=unknown-directory,different-app
```

###### `--allow-all` 

Enables all `--allow-*` flags at once.

```sh
ggt push --force --allow-all
```

###### `--allow-unknown-directory` 

Pushes changes from any local directory with existing files, even if the `.gadget/sync.json` file is missing.

```sh
ggt push --allow-unknown-directory
```

###### `--allow-different-app` 

Pushes changes to a different app using `--app` command, instead of the one in the `.gadget/sync.json` file.

```sh
ggt push --app task-manager --allow-different-app
```

### **`ggt pull`** 

Pulls your environment files to your local directory.

This command tracks changes in your local directory since the last sync (`ggt dev`, `ggt push`, `ggt pull`). If changes have been detected, you will be prompted to discard them or abort the pull.

##### Usage 

```sh-session
ggt pull [options]
```

##### Examples 

Pull all changes from a `main` environment by discarding any changes made on the local directory:

```sh
ggt pull --env main --force
```

Pull and skip all interactive prompts:

```sh
ggt pull --force --allow-all
```

##### Options 

###### `-a` `--app <app_name>` 

Selects the app to pull your environment changes from.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt pull --app my-blog
```

###### `-e` `--env <env_name>` 

Selects the environment to pull changes from.

If not specified, defaults to the environment set in `.gadget/sync.json`.

```sh
ggt pull --env main
```

###### `--force` 

Forces a pull by discarding any changes made on the local directory since the last sync (`ggt dev`, `ggt push`, `ggt pull`).

```sh
ggt pull --force
```

###### `--allow <flag,...>` 

Enables specific `--allow-*` flags using a comma-separated shorthand. Passing `all` as a value enables all flags, equivalent to `--allow-all`. If an unknown value is passed, `ggt` suggests the closest valid match.

Valid values are `unknown-directory` and `different-app`.

```sh
ggt pull --allow=unknown-directory,different-app
```

###### `--allow-all` 

Enables all `--allow-*` flags at once.

```sh
ggt pull --force --allow-all
```

###### `--allow-unknown-directory` 

Pulls changes to any local directory with existing files, even if the `.gadget/sync.json` file is missing.

```sh
ggt pull --allow-unknown-directory
```

###### `--allow-different-app` 

Pulls changes from a different app using the `--app` command, rather than the one specified in the `.gadget/sync.json` file.

```sh
ggt pull --allow-different-app
```

### **`ggt var`** 

Manages environment variables for your development and production environments.

##### Usage 

List all environment variable keys:

```sh-session
ggt var list [options]
```

Get the value of a variable:

```sh-session
ggt var get <key> [options]
```

Set one or more variables:

```sh-session
ggt var set <key=value> [key=value ...] [options]
```

*   **`--secret`** Marks the variable or variables as secret. Secret values are encrypted and cannot be read back with `ggt var get`.

Delete one or more variables:

```sh-session
ggt var delete <key> [key ...] [options]
```

*   **`-f` `--force`** Skips the confirmation prompt and suppresses errors for variables that do not exist.
*   **`--all`** Targets all variables instead of requiring individual keys to be specified.

Import variables from another environment or a `.env` file:

```sh-session
ggt var import [options] [key ...]
```

*   **`--all`** Targets all variables instead of requiring individual keys to be specified.
*   **`--from <env>`** Imports variables from another environment of the same application. Variables are imported as empty placeholders unless `--include-values` is also passed.
*   **`--from-file <path>`** Imports variables from a `.env` file. Lines starting with `#` and blank lines are skipped. The `export` prefix and surrounding quotes are stripped automatically.
*   **`--include-values`** Copies the actual values from the source environment instead of importing as empty placeholders. Secret variables are always skipped because their values are not accessible.

##### Examples 

List all variable keys in a development environment:

```sh
$ ggt var list --app my-app --env development
```

Get the value of a variable:

```sh
$ ggt var get DATABASE_URL --app my-app --env development
```

Set a variable:

```sh
$ ggt var set API_KEY=abc123 --app my-app --env development
```

Set a secret variable:

```sh
$ ggt var set SECRET_TOKEN=xyz --secret --app my-app --env development
```

Set multiple variables at once:

```sh
$ ggt var set KEY1=val1 KEY2=val2
```

Delete a variable:

```sh
$ ggt var delete API_KEY --app my-app --env development
```

Delete all variables without a confirmation prompt:

```sh
$ ggt var delete --all --force
```

Import all keys from a `staging` environment as empty placeholders:

```sh
$ ggt var import --from staging --all --app my-app --env development
```

Import specific keys with their values from `staging`:

```sh
$ ggt var import --from staging --include-values API_KEY DATABASE_URL
```

Import all variables from a `.env` file:

```sh
$ ggt var import --from-file .env.example --all
```

##### Options 

###### `-a` `--app <app_name>` 

Selects the application.

If not specified, defaults to the app set in `.gadget/sync.json`.

###### `-e` `--env <env_name>` 

Selects the environment.

If not specified, defaults to the environment set in `.gadget/sync.json`.

### **`ggt model`** 

Adds and manages models in your app.

Model commands sync local files with the environment before making schema changes. Use `ggt model add` to scaffold a new model, `ggt model remove` to delete an existing model, and `ggt model rename` to move a model to a new path.

##### Usage 

```sh-session
ggt model <command> [flags]
```

Add a model:

```sh-session
ggt model add <name> [field:type ...] [flags]
```

*   **`<name>`** The model path. For `ggt model add`, this becomes the model API identifier in your client code, such as `api.post`.
*   **`[field:type ...]`** Optional field definitions for `ggt model add`. Each definition is a `name:type` pair, such as `title:string`.
*   Supported field types include `string`, `number`, `boolean`, `datetime`, `json`, `email`, `url`, `vector`, `richtext`, `file`, `enum`, and `color`.

Remove a model:

```sh-session
ggt model remove <name> [flags]
```

Rename a model:

```sh-session
ggt model rename <name> <new-name> [flags]
```

##### Examples 

Add a new `post` model:

```sh
$ ggt model add post
```

Add a namespaced `blog/post` model:

```sh
$ ggt model add blog/post
```

Add a new `post` model with `title` and `body` fields:

```sh
$ ggt model add post title:string body:string
```

Remove the `post` model:

```sh
$ ggt model remove post
```

Remove the `post` model without a confirmation prompt:

```sh
$ ggt model remove post --force
```

Rename `post` to `article`:

```sh
$ ggt model rename post article
```

Rename a namespaced model:

```sh
$ ggt model rename blog/post blog/article
```

##### Options 

###### `-a` `--app <app_name>` 

Selects the application.

If not specified, defaults to the app set in `.gadget/sync.json`.

###### `-e` `--env <env_name>` 

Selects the environment.

If not specified, defaults to the development environment.

###### `-f` `--force` 

Skips the confirmation prompt for `ggt model remove`.

```sh
ggt model remove post --force
```

###### `--allow <flag,...>` 

Enables specific `--allow-*` flags using a comma-separated shorthand. Passing `all` as a value enables all flags, equivalent to `--allow-all`.

Valid values are `unknown-directory` and `different-app`.

```sh
ggt model add post --allow=unknown-directory,different-app
```

###### `--allow-all` 

Enables all `--allow-*` flags at once.

```sh
ggt model add post --allow-all
```

###### `--allow-unknown-directory` 

Allows syncing to an existing directory, even if it does not already contain `.gadget/sync.json`.

```sh
ggt model add post --allow-unknown-directory
```

###### `--allow-different-app` 

Allows syncing with a different app than the one recorded in `.gadget/sync.json`.

```sh
ggt model add post --app task-manager --allow-different-app
```

### **`ggt action`** 

Adds and manages actions in your app.

Actions run server-side code in your app. Use `ggt action add` to scaffold a global action or a model action.

##### Usage 

```sh-session
ggt action <command> [flags]
```

Add an action:

```sh-session
ggt action add <name> [flags]
```

*   **`<name>`** The action API identifier. This can include namespaces as folders, such as `notifications/sendWelcomeEmail`.

##### Examples 

Add a global action:

```sh
$ ggt action add sendWelcomeEmail
```

Add a namespaced global action:

```sh
$ ggt action add notifications/sendWelcomeEmail
```

Add a `publish` action to the `post` model:

```sh
$ ggt action add publish --model post
```

Add a model action to a namespaced model:

```sh
$ ggt action add fulfill --model billing/invoice
```

##### Options 

###### `-a` `--app <app_name>` 

Selects the application.

If not specified, defaults to the app set in `.gadget/sync.json`.

###### `-e` `--env <env_name>` 

Selects the environment.

If not specified, defaults to the development environment.

###### `--model <model_name>` 

Adds the action to an existing model instead of creating a global action.

The model API identifier can include namespaces, such as `billing/invoice`.

```sh
ggt action add publish --model post
```

###### `--allow <flag,...>` 

Enables specific `--allow-*` flags using a comma-separated shorthand. Passing `all` as a value enables all flags, equivalent to `--allow-all`.

Valid values are `unknown-directory` and `different-app`.

```sh
ggt action add sendWelcomeEmail --allow=unknown-directory,different-app
```

###### `--allow-all` 

Enables all `--allow-*` flags at once.

```sh
ggt action add sendWelcomeEmail --allow-all
```

###### `--allow-unknown-directory` 

Allows syncing to an existing directory, even if it does not already contain `.gadget/sync.json`.

```sh
ggt action add sendWelcomeEmail --allow-unknown-directory
```

###### `--allow-different-app` 

Allows syncing with a different app than the one recorded in `.gadget/sync.json`.

```sh
ggt action add sendWelcomeEmail --app task-manager --allow-different-app
```

### **`ggt add`** 

Adds models, fields, actions, and routes to your app, or adds a new development environment.

This command first performs a sync to ensure that your local and environment directories match. Changes are tracked since the last sync (`ggt dev`, `ggt pull`, `ggt push`). If any conflicts are detected, you will be asked to resolve them before `ggt add` can be run.

Use [ggt model](https://docs.gadget.dev/reference/ggt#ggt-model) and [ggt action](https://docs.gadget.dev/reference/ggt#ggt-action) for dedicated model and action command groups. `ggt add` remains useful for fields, routes, environments, and direct resource scaffolding.

##### Usage 

Add a model:

```sh-session
ggt add model <model_name> [field_name:field_type ...]
```

Add a field to an existing model:

```sh-session
ggt add field <model_name>/<field_name>:<field_type>
```

Add an action:

```sh-session
ggt add action [CONTEXT]/<action_name>
```

Add an HTTP route:

```sh-session
ggt add route <HTTP_METHOD>-<route_path>
```

Add a development environment:

```markdown
ggt add environment <environment_name> --env <environment_to_clone>
```

##### Examples 

Add a new **model** `post` without fields:

```sh
$ ggt add model post
```

Add a new **model** `post` with 2 new `string` type fields, `title` and `body`:

```sh
$ ggt add model post title:string body:string
```

Add a new **model** `post` under namespace `blogs`:

```sh
$ ggt add model blogs/post
```

Add a new `boolean` **field** `published` to an existing `post` model:

```sh
$ ggt add field post/published:boolean
```

Add a new `string` **field** `title` to an existing `post` model under namespace `blogs`:

```sh
$ ggt add field blogs/post/title:string
```

Add a new **action** `publish` to the existing `post` model:

```sh
$ ggt add action post/publish
```

Add a new **action** `audit`:

```sh
$ ggt add action audit
```

Add a new **action** `sendSms` under namespace `notifications`:

```sh
$ ggt add action notifications/sendSms
```

Add a new GET **route** `howdy`:

```sh
$ ggt add route GET howdy
```

Add a new `dev-2` development environment, cloning the existing `development` environment:

```sh
$ ggt add environment dev-2 --env development
```

##### Shared namespaces 

If you have a namespace shared between actions and models, `ggt` will prompt you to specify where you want to add the new item.

You can also set the `CONTEXT` to `model` or `action` to avoid the prompt.

Add an `audit` **action** under the `post` model:

```sh
$ ggt add action model/post/audit
```

Add an `audit` **action** under the `post` action namespace:

```sh
$ ggt add action action/post/audit
```

##### Options 

###### `-e` `--env <env_name>` 

Selects the environment to add to. Required for `ggt add environment` to specify the existing environment to clone.

If not specified, defaults to the environment set in `.gadget/sync.json`.

### **`ggt env`** 

Manages environments for your Gadget application. `ggt envs` is an alias for `ggt env`.

Unlike `ggt add environment`, this command does not require an active sync context. It resolves the application from the `--app` flag, `.gadget/sync.json`, or an interactive prompt.

##### Usage 

List all environments:

```sh-session
ggt env list [options]
```

```sh-session
ggt env ls [options]
```

Create a new environment:

```sh-session
ggt env create <name> [options]
```

*   **`--from <env_name>`** Clones the new environment from the specified existing environment. If not specified, defaults to the current sync environment when run from a synced directory. Otherwise, the new environment is created empty.
*   **`--use`** Switches to the new environment after creation by updating `.gadget/sync.json`.

Delete an environment:

```sh-session
ggt env delete <name> [options]
```

*   **`-f` `--force`** Skips the confirmation prompt before deleting.

Unpause a paused environment:

```sh-session
ggt env unpause <name> [options]
```

Switch the active environment in the current sync directory:

```sh-session
ggt env use <name> [options]
```

**`ggt env use`** cannot switch to the production environment. Use `ggt pull --env=production` to pull from production instead.

##### Examples 

List all environments for the `my-blog` app:

```sh
$ ggt env list --app my-blog
```

Create a new `dev-2` environment:

```sh
$ ggt env create dev-2 --app my-blog
```

Create a `dev-2` environment cloned from `development`:

```sh
$ ggt env create dev-2 --from development --app my-blog
```

Create a `dev-2` environment and immediately switch to it:

```sh
$ ggt env create dev-2 --use --app my-blog
```

Delete the `dev-2` environment, skipping confirmation:

```sh
$ ggt env delete dev-2 --force --app my-blog
```

Unpause the `dev-2` environment:

```sh
$ ggt env unpause dev-2 --app my-blog
```

Switch the current sync directory to `dev-2`:

```sh
$ ggt env use dev-2
```

##### Options 

###### `-a` `--app <app_name>` 

Selects the application to manage environments for.

If not specified, defaults to the app set in `.gadget/sync.json`, or prompts interactively.

```sh
ggt env list --app my-blog
```

### **`ggt open`** 

This command opens a specific Gadget page in your browser, allowing you to directly access various parts of your application's interface such as logs, permissions, data views, or model schemas.

##### Usage 

```sh-session
ggt open [LOCATION] [MODEL] [options]
```

##### Examples 

Opens editor home:

```sh
$ ggt open
```

Opens logs:

```sh
$ ggt open logs
```

Opens permissions:

```sh
$ ggt open permissions
```

Opens data editor for the `post` model:

```sh
$ ggt open data post
```

Opens schema for `post` model:

```sh
$ ggt open schema post
```

Shows all models available in the data editor:

```sh
$ ggt open data --show-all
```

Shows all models available in the schema viewer:

```sh
$ ggt open schema --show-all
```

Opens data editor for `post` model of app `my-blog` in the `staging` environment:

```sh
$ ggt open data post --app my-blog --env staging
```

##### Arguments 

###### `LOCATION` 

Specifies the page to open in Gadget, must be one of the following:

*   **logs** Opens the **Logs** page.
*   **permissions** Opens `accessControl/permissions`.
*   **data** Opens the **data** editor for a specific model.
*   **schema** Opens the **schema** editor for a specific model.

##### Options 

###### `-a` `--app <name>` 

Select the application to open in your browser.

If not specified, defaults to the app set in `.gadget/sync.json`.

```sh
ggt open data post --app my-blog
```

###### `-e` `--env <env>` 

Select the environment to open in your browser.

If not specified, defaults to the environment set in `.gadget/sync.json`.

```sh
ggt open logs --env staging
```

###### `--show-all` 

Shows all schema or data options by listing your available models.

```sh
ggt open data --show-all
```

### **`ggt list`** 

List the apps available to the currently logged-in user.

##### Usage 

```sh
ggt list
```

### **`ggt login`** 

Log in to your account.

##### Usage 

```sh
ggt login
```

### **`ggt logout`** 

Log out of your account.

##### Usage 

```sh
ggt logout
```

### **`ggt whoami`** 

Show the name and email address of the currently logged-in user.

##### Usage 

```sh
ggt whoami
```

### **`ggt configure`** 

Manages default `ggt` configuration.

This command manages saved defaults for global `ggt` options.

You can use it to control whether `ggt` sends telemetry and crash reports to Gadget, and whether commands that support structured output default to JSON output.

##### Usage 

Show current configured defaults:

```sh-session
ggt configure show
```

Interactively change configuration:

```sh-session
ggt configure change
```

Clear all configured defaults:

```sh-session
ggt configure clear
```

##### Configurable options 

###### `telemetry` 

Controls whether `ggt` sends anonymous telemetry and crash reports to Gadget.

When enabled, `ggt` can send diagnostic information that helps us improve the CLI and investigate failures.

Defaults to `true`.

###### `json` 

Controls whether `ggt` defaults to JSON output for commands that support `--json`.

When enabled, supported commands print newline-delimited JSON by default instead of the standard human-readable output.

Defaults to `false`.

### **`ggt completion`** 

Generates a shell completion script for `ggt` and prints it to stdout. Writing the generated script to a file and sourcing it in your shell configuration enables tab completion for `ggt` commands, subcommands, flags, and dynamic values such as app names and environment names.

Shell completion scripts hook into your shell so that pressing Tab while typing a `ggt` command suggests valid completions. For example, typing `ggt dev --app` and pressing Tab will list your available Gadget apps. Re-run the generation command after updating `ggt` to keep completions current.

If `ggt` is not installed globally, use `npx ggt` in place of `ggt` in the commands below.

##### Usage 

```sh-session
ggt completion <shell>
```

##### Subcommands 

###### `bash` 

Generates a bash completion script.

```sh-session
ggt completion bash
```

To enable completions, write the script to a file and source it from your `~/.bashrc` (or `~/.bash_profile` on macOS):

```sh
mkdir -p ~/.local/share/ggt
ggt completion bash > ~/.local/share/ggt/completion.bash
```

Then add this line to your `~/.bashrc` (or `~/.bash_profile` on macOS):

```sh
source "$HOME/.local/share/ggt/completion.bash"
```

###### `zsh` 

Generates a zsh completion script.

```sh-session
ggt completion zsh
```

To enable completions, write the script to a file and source it from your `~/.zshrc`:

```sh
mkdir -p ~/.local/share/ggt
ggt completion zsh > ~/.local/share/ggt/completion.zsh
```

Then add this line to your `~/.zshrc`:

```sh
source "$HOME/.local/share/ggt/completion.zsh"
```

If you get `command not found: compdef`, add the following line before the `source` line:

```sh
autoload -Uz compinit && compinit
```

###### `fish` 

Generates a fish completion script.

```sh-session
ggt completion fish
```

To enable completions, write the script to the fish completions directory:

```sh
ggt completion fish > ~/.config/fish/completions/ggt.fish
```

Fish loads all scripts in `~/.config/fish/completions/` automatically on startup.

### **`ggt agent-plugin`** 

Install Gadget agent plugins, `AGENTS.md` and Gadget agent skills, into your current project.

##### Usage 

Install agent skills and context into the current project:

```sh-session
ggt agent-plugin install [--force]
```

Update existing agent context files:

```sh
ggt agent-plugin update
```

##### Example 

Install the default Gadget agent context files in your current project:

```sh
ggt agent-plugin install
```

##### Options 

###### `--force` 

Overwrite or reinstall the files even if they are already present.

```sh
ggt agent-plugin install --force
```

### **`ggt version`** 

Print the version of `ggt`.

##### Usage 

```sh
  ggt version
```