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

Utilities

  • add Add models, fields, actions, and routes to your app.
  • open Open Gadget in your default browser.
  • list List your available applications.

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  

Print command's usage.

-v --verbose 

Print verbose output.

--json 

Print output as JSON.


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.

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 ~/gadget/my-blog and keep it up to date with the development environment:

terminal
ggt dev ~/gadget/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 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-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 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 add 

Adds models, fields, actions, and routes to your app.

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

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


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

Print the version of ggt.

Usage 
terminal
ggt version