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

  • add Add models, fields, actions, and routes to your app.
  • env Manage environments for your application.
  • configure Manage default ggt configuration.
  • 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-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 

Streams logs from your app in real time.

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 

Stream logs for the app in .gadget/sync.json:

terminal
$ ggt logs

Stream 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 
-a --app <app_name> 

Selects the application whose logs you want to stream.

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

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")'

--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]
Example 

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

terminal
$ ggt deploy --app my-blog --from staging
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-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]
Example 

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

terminal
ggt push --env main --force
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-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]
Example 

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

terminal
ggt pull --env main --force
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-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 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.

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

ggt login 

Log in to your account.

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

Was this page helpful?