`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:

terminal
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:

terminal
npm install -g ggt@latest

Usage

terminal
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.
field Add and manage fields on 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.
shopify Manage your Shopify connection.
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 for dependency management during synchronization.

Avoid fatal errors

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

terminal
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:

terminal
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.

terminal
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.

terminal
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.

terminal
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.

terminal
ggt dev --allow=unknown-directory,different-app

`--allow-all`

Enables all --allow-* flags at once.

terminal
ggt dev --allow-all

`--allow-unknown-directory`

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

terminal
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.

terminal
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 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 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

terminal
ggt debugger [--configure <editor>]

Example

Configure VS Code for debugging:

terminal
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

terminal
ggt logs [options]

Examples

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

terminal
$ ggt logs

Stream logs continuously:

terminal
$ ggt logs --follow

Print logs from a specific point in time:

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

Print logs from production:

terminal
$ ggt logs --env production

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

terminal
$ ggt logs --my-logs --log-level warn

Output logs as JSON:

terminal
$ ggt logs --json

Options

`-f` `--follow`

Streams logs continuously instead of printing recent logs and exiting.

terminal
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.

terminal
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.

terminal
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.

terminal
ggt logs --env staging

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

Sets the minimum log level to display.

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

terminal
ggt logs --log-level debug

`-m` `--my-logs`

Shows only logs emitted by your code.

This filters out built-in platform logs.

terminal
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

terminal
ggt problems [options]

Examples

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

terminal
$ ggt problems

Check a specific app and environment:

terminal
$ 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.

terminal
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.

terminal
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

terminal
ggt eval [options] <snippet>

Examples

Fetch all users from your app:

terminal
$ ggt eval 'api.user.findMany()'

Run against a specific app and environment:

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

Run a write operation:

terminal
$ 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.

terminal
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.

terminal
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.

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

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

Valid values are writes.

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

`--allow-all`

Enables all --allow-* flags at once.

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

`--json`

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

terminal
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

terminal
ggt deploy [options]

Examples

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

terminal
$ ggt deploy --app my-blog --from staging

Deploy and skip all interactive prompts:

terminal
$ ggt deploy --force --allow-all

Deploy and skip specific interactive prompts:

terminal
$ 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.

terminal
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.

terminal
ggt deploy --from development

`-f` `--force`

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

Defaults to false.

terminal
ggt deploy --force

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

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

terminal
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.

terminal
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.

terminal
ggt deploy --allow-problems

`--allow-charges`

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

Defaults to false.

terminal
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.

terminal
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.

terminal
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.

terminal
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

terminal
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

terminal
ggt push [options]

Examples

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

terminal
ggt push --env main --force

Push and skip all interactive prompts:

terminal
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.

terminal
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.

terminal
ggt push --env staging

`-f` `--force`

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

terminal
ggt push --force

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

Valid values are unknown-directory and different-app.

terminal
ggt push --allow=unknown-directory,different-app

`--allow-all`

Enables all --allow-* flags at once.

terminal
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.

terminal
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.

terminal
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

terminal
ggt pull [options]

Examples

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

terminal
ggt pull --env main --force

Pull and skip all interactive prompts:

terminal
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.

terminal
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.

terminal
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).

terminal
ggt pull --force

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

Valid values are unknown-directory and different-app.

terminal
ggt pull --allow=unknown-directory,different-app

`--allow-all`

Enables all --allow-* flags at once.

terminal
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.

terminal
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.

terminal
ggt pull --allow-different-app

`ggt var`

Manages environment variables for your development and production environments.

Usage

List all environment variable keys:

terminal
ggt var list [options]

Get the value of a variable:

terminal
ggt var get <key> [options]

Set one or more variables:

terminal
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:

terminal
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:

terminal
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:

terminal
$ ggt var list --app my-app --env development

Get the value of a variable:

terminal
$ ggt var get DATABASE_URL --app my-app --env development

Set a variable:

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

Set a secret variable:

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

Set multiple variables at once:

terminal
$ ggt var set KEY1=val1 KEY2=val2

Delete a variable:

terminal
$ ggt var delete API_KEY --app my-app --env development

Delete all variables without a confirmation prompt:

terminal
$ ggt var delete --all --force

Import all keys from a staging environment as empty placeholders:

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

Import specific keys with their values from staging:

terminal
$ ggt var import --from staging --include-values API_KEY DATABASE_URL

Import all variables from a .env file:

terminal
$ 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 or enable a Shopify model, ggt model remove to delete an existing model, and ggt model rename to move a model to a new path.

Usage

terminal
ggt model <command> [flags]

Add a model:

terminal
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.
Use --type shopify to enable a Shopify model. Field definitions are not supported when adding a Shopify model. Use --resource <key> with --type shopify when the model path does not directly match the Shopify model key.

Remove a model:

terminal
ggt model remove <name> [flags]

Rename a model:

terminal
ggt model rename <name> <new-name> [flags]

Examples

Add a new post model:

terminal
$ ggt model add post

Add a namespaced blog/post model:

terminal
$ ggt model add blog/post

Add a new post model with title and body fields:

terminal
$ ggt model add post title:string body:string

Enable the shopifyProduct Shopify model:

terminal
$ ggt model add shopifyProduct --type shopify

Enable the shopifyProduct Shopify model at a custom path:

terminal
$ ggt model add shopify/product --type shopify --resource shopifyProduct

Remove the post model:

terminal
$ ggt model remove post

Remove the post model without a confirmation prompt:

terminal
$ ggt model remove post --force

Rename post to article:

terminal
$ ggt model rename post article

Rename a namespaced model:

terminal
$ 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.

terminal
ggt model remove post --force

`--type <type>`

Selects the type of model to add.

The only supported value is shopify. Use --type shopify to enable a Shopify sync model.

terminal
ggt model add shopifyProduct --type shopify

`--resource <key>`

Selects the Shopify model key to enable.

Use this with --type shopify when the model path does not directly match the Shopify model key.

terminal
ggt model add shopify/product --type shopify --resource shopifyProduct

`--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.

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

`--allow-all`

Enables all --allow-* flags at once.

terminal
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.

terminal
ggt model add post --allow-unknown-directory

`--allow-different-app`

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

terminal
ggt model add post --app task-manager --allow-different-app

`ggt field`

Adds and manages fields on models in your app.

Field commands sync local files with the environment before making schema changes. Use ggt field add to add scalar fields, relationship fields, and Shopify metafields, ggt field remove to delete a field, and ggt field rename to rename a field on the same model.

Usage

terminal
ggt field <command> [flags]

Add a field:

terminal
ggt field add <model/field:type> [flags]

<model/field:type> The model path, field API identifier, and field type. For example, post/title:string.
- Supported field types include number, string, richText, email, url, color, json, enum, boolean, dateTime, vector, file, encryptedString, computed, belongsTo, hasOne, hasMany, hasManyThrough, password, roleList, money, and recordState.

Remove a field:

terminal
ggt field remove <model/field> [flags]

Rename a field:

terminal
ggt field rename <model/field> <model/new-field-name> [flags]

Both paths passed to ggt field rename must reference the same model.

Examples

Add a boolean field to the post model:

terminal
$ ggt field add post/published:boolean

Add a required string field:

terminal
$ ggt field add post/title:string --required

Add a unique email field:

terminal
$ ggt field add user/email:email --unique

Add a field on a namespaced model:

terminal
$ ggt field add billing/invoice/dueDate:dateTime

Add a Shopify metafield to a Shopify model:

terminal
$ ggt field add shopifyProduct/spiciness:string --metafield --namespace custom --key spiciness --metafield-type single_line_text_field

Add a list Shopify metafield:

terminal
$ ggt field add shopifyProduct/relatedProductIds:json --metafield --namespace custom --metafield-type product_reference --list

Add a belongs to relationship:

terminal
$ ggt field add post/author:belongsTo --to user

Add a has many relationship:

terminal
$ ggt field add user/posts:hasMany --to post

Add a has many through relationship:

terminal
$ ggt field add post/tags:hasManyThrough --to tag --through postTag

Override the generated inverse field name:

terminal
$ ggt field add post/author:belongsTo --to user --inverse-field authoredPosts

Remove a field:

terminal
$ ggt field remove post/title

Remove a field without a confirmation prompt:

terminal
$ ggt field remove post/title --force

Rename a field:

terminal
$ ggt field rename post/title post/heading

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.

`--required`

Marks a new field as required.

Only supported by ggt field add.

terminal
ggt field add post/title:string --required

`--unique`

Marks a new field as unique.

Only supported by ggt field add.

terminal
ggt field add user/email:email --unique

`--metafield`

Links a new field to a Shopify metafield.

Only supported by ggt field add. Use this flag with Shopify models. --namespace and --metafield-type are required when --metafield is used.

terminal
ggt field add shopifyProduct/spiciness:string --metafield --namespace custom --metafield-type single_line_text_field

`--namespace <namespace>`

Sets the Shopify metafield namespace.

Required when --metafield is used.

terminal
ggt field add shopifyProduct/spiciness:string --metafield --namespace custom --metafield-type single_line_text_field

`--key <key>`

Sets the Shopify metafield key.

Only used with --metafield. If not specified, the key defaults to the field API identifier.

terminal
ggt field add shopifyProduct/spiciness:string --metafield --namespace custom --key spiceLevel --metafield-type single_line_text_field

`--metafield-type <type>`

Sets the Shopify metafield type.

Required when --metafield is used.

terminal
ggt field add shopifyProduct/spiciness:string --metafield --namespace custom --metafield-type single_line_text_field

`--list`

Stores a list of Shopify metafield values.

Only used with --metafield.

terminal
ggt field add shopifyProduct/relatedProductIds:json --metafield --namespace custom --metafield-type product_reference --list

`--to <model>`

Sets the target model for a relationship field.

Required for belongsTo, hasOne, hasMany, and hasManyThrough fields. This flag is only valid for relationship fields.

terminal
ggt field add post/author:belongsTo --to user

`--through <model>`

Sets the join model for a hasManyThrough relationship field.

Required for hasManyThrough fields. This flag is only valid for hasManyThrough fields.

terminal
ggt field add post/tags:hasManyThrough --to tag --through postTag

`--inverse-field <field>`

Overrides the generated inverse field name on the related model.

Only valid for relationship fields.

terminal
ggt field add post/author:belongsTo --to user --inverse-field authoredPosts

`-f` `--force`

Skips the confirmation prompt for ggt field remove.

terminal
ggt field remove post/title --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.

terminal
ggt field add post/title:string --allow=unknown-directory,different-app

`--allow-all`

Enables all --allow-* flags at once.

terminal
ggt field add post/title:string --allow-all

`--allow-unknown-directory`

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

terminal
ggt field add post/title:string --allow-unknown-directory

`--allow-different-app`

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

terminal
ggt field add post/title:string --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

terminal
ggt action <command> [flags]

Add an action:

terminal
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:

terminal
$ ggt action add sendWelcomeEmail

Add a namespaced global action:

terminal
$ ggt action add notifications/sendWelcomeEmail

Add a publish action to the post model:

terminal
$ ggt action add publish --model post

Add a model action to a namespaced model:

terminal
$ 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.

terminal
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.

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

`--allow-all`

Enables all --allow-* flags at once.

terminal
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.

terminal
ggt action add sendWelcomeEmail --allow-unknown-directory

`--allow-different-app`

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

terminal
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, ggt field, and ggt action for dedicated model, field, and action command groups. ggt add remains useful for routes, environments, and direct resource scaffolding.

Usage

Add a model:

terminal
ggt add model <model_name> [field_name:field_type ...]

Add a field to an existing model:

terminal
ggt add field <model_name>/<field_name>:<field_type>

Add an action:

terminal
ggt add action [CONTEXT]/<action_name>

Add an HTTP route:

terminal
ggt add route <HTTP_METHOD>-<route_path>

Add a development environment:


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

Examples

Add a new model post without fields:

terminal
$ ggt add model post

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

terminal
$ ggt add model post title:string body:string

Add a new model post under namespace blogs:

terminal
$ ggt add model blogs/post

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

terminal
$ ggt add field post/published:boolean

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

terminal
$ ggt add field blogs/post/title:string

Add a new action publish to the existing post model:

terminal
$ ggt add action post/publish

Add a new action audit:

terminal
$ ggt add action audit

Add a new action sendSms under namespace notifications:

terminal
$ ggt add action notifications/sendSms

Add a new GET route howdy:

terminal
$ ggt add route GET howdy

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

terminal
$ 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:

terminal
$ ggt add action model/post/audit

Add an audit action under the post action namespace:

terminal
$ 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 shopify` Framework v1.7.0+

Manages the Shopify connection for your Gadget app.

`ggt shopify connect`

Configure the Shopify connection:

terminal
ggt shopify connect [flags]

ggt shopify connect imports your local Shopify CLI session, creates the Shopify connection files, and syncs them into your project. If you have not authenticated with Shopify locally, run shopify auth login before running this command.

The command creates development and production Shopify app configs, adds the default Shopify models, and adds the required default Shopify scopes.

Examples:

Configure the Shopify connection for the app in .gadget/sync.json:

terminal
$ ggt shopify connect

Configure the connection with a custom Shopify app name:

terminal
$ ggt shopify connect --app-name my-shop

Configure the connection for a specific Shopify organization:

terminal
$ ggt shopify connect --shopify-organization-id 123456789

`ggt shopify status`

Show Shopify connection status:

terminal
ggt shopify status [flags]

ggt shopify status prints:

The current Shopify API version and whether a newer version is available.
Enabled Shopify models.
The authenticated Shopify partner account.
The connected Shopify app name and client ID.
Requested Shopify scopes.
Registered webhook topics.

Examples:

Show the Shopify connection status:

terminal
$ ggt shopify status

Sample output:


text
API version:            2024-04 (2026-04 available)
Enabled models:        shopifyProduct | shopifyVariant
Authed partner account: [email protected]
App:                    my-gadget-app (client_id: abc123)
Scopes:                 read_orders | write_products
Webhook topics:         app/uninstalled | orders/create | orders/updated

`ggt shopify sync`

Start a Shopify data sync:

terminal
ggt shopify sync [flags]

ggt shopify sync starts Shopify data syncs for installed shops.

With no selector, all valid installed shops are synced. By default, the command syncs the last 10 records per Shopify model. Use --store or --shop-ids to sync specific shops, --models to sync specific Shopify models, --since to sync records updated since a date, --last to change the default record limit, or --all to sync all matching records.

Examples:

Start a sync for all valid installed shops. By default, this syncs the last 10 records per Shopify model:

terminal
$ ggt shopify sync

Start a sync for one installed store:

terminal
$ ggt shopify sync --store mystore.myshopify.com

Start a sync for specific shopifyShop record IDs:

terminal
$ ggt shopify sync --shop-ids 1,2,3

Start a sync for specific Shopify models:

terminal
$ ggt shopify sync --models shopifyProduct,shopifyOrder

Start a sync for records updated since a date:

terminal
$ ggt shopify sync --since 2024-01-01

Start a sync for the last 50 records per model:

terminal
$ ggt shopify sync --last 50

Start a sync for all matching records:

terminal
$ ggt shopify sync --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.

`--app-name <name>`

Sets the Shopify app name created by ggt shopify connect.

Only supported by ggt shopify connect. If not specified, defaults to your Gadget app slug.

terminal
ggt shopify connect --app-name my-shop

`--shopify-organization-id <id>`

Sets the Shopify organization ID used by ggt shopify connect.

Only supported by ggt shopify connect. Use this flag when your Shopify account has multiple organizations.

terminal
ggt shopify connect --shopify-organization-id 123456789

`--store <domain>`

Syncs one installed store by domain.

Only supported by ggt shopify sync. Cannot be combined with --shop-ids.

terminal
ggt shopify sync --store mystore.myshopify.com

`--shop-ids <ids>`

Syncs specific shopifyShop records by ID.

Only supported by ggt shopify sync. Pass a comma-separated list. Cannot be combined with --store.

terminal
ggt shopify sync --shop-ids 1,2,3

`--models <models>`

Syncs specific Shopify models.

Only supported by ggt shopify sync. Pass a comma-separated list of model API identifiers.

terminal
ggt shopify sync --models shopifyProduct,shopifyOrder

`--since <date>`

Syncs records updated since the given date.

Only supported by ggt shopify sync. Use a date value like 2024-01-01.

terminal
ggt shopify sync --since 2024-01-01

`--last <count>`

Syncs the last number of records per Shopify model.

Only supported by ggt shopify sync. Defaults to 10. Cannot be combined with --all.

terminal
ggt shopify sync --last 50

`--all`

Syncs all matching records instead of the default last 10 records per Shopify model.

Only supported by ggt shopify sync. Cannot be combined with --last.

terminal
ggt shopify sync --all

`--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.

terminal
ggt shopify status --allow=unknown-directory,different-app

`--allow-all`

Enables all --allow-* flags at once.

terminal
ggt shopify status --allow-all

`--allow-unknown-directory`

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

terminal
ggt shopify status --allow-unknown-directory

`--allow-different-app`

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

terminal
ggt shopify status --app task-manager --allow-different-app

`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:

terminal
ggt env list [options]

terminal
ggt env ls [options]

Create a new environment:

terminal
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:

terminal
ggt env delete <name> [options]

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

Unpause a paused environment:

terminal
ggt env unpause <name> [options]

Switch the active environment in the current sync directory:

terminal
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:

terminal
$ ggt env list --app my-blog

Create a new dev-2 environment:

terminal
$ ggt env create dev-2 --app my-blog

Create a dev-2 environment cloned from development:

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

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

terminal
$ ggt env create dev-2 --use --app my-blog

Delete the dev-2 environment, skipping confirmation:

terminal
$ ggt env delete dev-2 --force --app my-blog

Unpause the dev-2 environment:

terminal
$ ggt env unpause dev-2 --app my-blog

Switch the current sync directory to dev-2:

terminal
$ 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.

terminal
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

terminal
ggt open [LOCATION] [MODEL] [options]

Examples

Opens editor home:

terminal
$ ggt open

Opens logs:

terminal
$ ggt open logs

Opens permissions:

terminal
$ ggt open permissions

Opens data editor for the post model:

terminal
$ ggt open data post

Opens schema for post model:

terminal
$ ggt open schema post

Shows all models available in the data editor:

terminal
$ ggt open data --show-all

Shows all models available in the schema viewer:

terminal
$ ggt open schema --show-all

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

terminal
$ 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.

terminal
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.

terminal
ggt open logs --env staging

`--show-all`

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

terminal
ggt open data --show-all

`ggt list`

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

Usage

terminal
ggt list

Usage

terminal
ggt login

`ggt logout`

Log out of your account.

Usage

terminal
ggt logout

`ggt whoami`

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

Usage

terminal
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:

terminal
ggt configure show

Interactively change configuration:

terminal
ggt configure change

Clear all configured defaults:

terminal
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

terminal
ggt completion <shell>

Subcommands

`bash`

Generates a bash completion script.

terminal
ggt completion bash

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

terminal
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):

terminal
source "$HOME/.local/share/ggt/completion.bash"

`zsh`

Generates a zsh completion script.

terminal
ggt completion zsh

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

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

Then add this line to your ~/.zshrc:

terminal
source "$HOME/.local/share/ggt/completion.zsh"

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

terminal
autoload -Uz compinit && compinit

`fish`

Generates a fish completion script.

terminal
ggt completion fish

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

terminal
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:

terminal
ggt agent-plugin install [--force]

Update existing agent context files:

terminal
ggt agent-plugin update

Example

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

terminal
ggt agent-plugin install

Options

`--force`

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

terminal
ggt agent-plugin install --force

`ggt version`

Print the version of ggt.

Usage

terminal
ggt version

ggt Reference

Install ggt

Update ggt

Usage

List of ggt commands

Global options

-h --help

-v --verbose

--json

--version

Commands

ggt dev

Usage

Example

Arguments

DIRECTORY

Options

-a --app <app_name>

-e --env <env_name>

--prefer <filesystem>

--allow <flag,...>

--allow-all

--allow-unknown-directory

--allow-different-app

Ignore files

ggt debugger

Usage

Example

Options

--configure <editor>

ggt logs

Usage

Examples

Options

-f --follow

--start <datetime>

-a --app <app_name>

-e --env <env_name>

-l --log-level <level>

-m --my-logs

ggt problems

Usage

Examples

Options

-a --app <app_name>

-e --env <env_name>

ggt eval

Usage

Examples

Arguments

<snippet>

Options

-a --app <app_name>

-e --env <env_name>

-w --allow-writes

--allow <flag,...>

--allow-all

--json

ggt deploy

Usage

Examples

Options

-a --app <app_name>

-e --env --from <env_name>

-f --force

--allow <flag,...>

--allow-all

--allow-problems --allow-issues

--allow-charges

--allow-data-delete

--allow-unknown-directory

--allow-different-app

ggt status

Usage

ggt push

Usage

Examples

Options

-a --app <app_name>

-e --env <env_name>

`ggt` Reference

Install `ggt`

Update `ggt`

List of `ggt` commands

`-h` `--help`

`-v` `--verbose`

`--json`

`--version`

`ggt dev`

`DIRECTORY`

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

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

`--prefer <filesystem>`

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

`--allow-all`

`--allow-unknown-directory`

`--allow-different-app`

`ggt debugger`

`--configure <editor>`

`ggt logs`

`-f` `--follow`

`--start <datetime>`

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

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

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

`-m` `--my-logs`

`ggt problems`

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

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

`ggt eval`

`<snippet>`

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

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

`-w` `--allow-writes`

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

`--allow-all`

`--json`

`ggt deploy`

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

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

`-f` `--force`

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

`--allow-all`

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

`--allow-charges`

`--allow-data-delete`

`--allow-unknown-directory`

`--allow-different-app`

`ggt status`

`ggt push`

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

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

`-f` `--force`

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

`--allow-all`

`--allow-unknown-directory`

`--allow-different-app`

`ggt pull`

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

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

`--force`

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

`--allow-all`

`--allow-unknown-directory`

`--allow-different-app`

`ggt var`

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

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

`ggt model`

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

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

`-f` `--force`

`--type <type>`

`--resource <key>`

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

`--allow-all`

`--allow-unknown-directory`

`--allow-different-app`

`ggt field`

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