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.
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 a new modelpost with 2 new string type fields, title and body:
terminal
$ ggt add model post title:string body:string
Add a new modelpost under namespace blogs:
terminal
$ ggt add model blogs/post
Add a new booleanfieldpublished to an existing post model:
terminal
$ ggt add field post/published:boolean
Add a new stringfieldtitle to an existing post model under namespace blogs:
terminal
$ ggt add field blogs/post/title:string
Add a new actionpublish to the existing post model:
terminal
$ ggt add action post/publish
Add a new actionaudit:
terminal
$ ggt add action audit
Add a new actionsendSms under namespace notifications:
terminal
$ ggt add action notifications/sendSms
Add a new GET routehowdy:
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 auditaction under the post model:
terminal
$ ggt add action model/post/audit
Add an auditaction 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.