ggt - the Gadget CLI 

Gadget's CLI, named ggt, is the command-line interface for the Gadget platform.

ggt provides additional functionality for working with your Gadget applications using your existing tools on your machine. ggt isn't required for building end-to-end Gadget apps but supports syncing files locally (and more soon) for your preferred coding experience.

Cloning files 

ggt allows you to clone your app's files into a local directory and sync any changes between your local directory and the Gadget editor (in real time!).

With your app's files on your local computer, you can use your favorite code editor, like VSCode or Sublime, to work on your Gadget apps. You can set up your own lint rules, write and run unit tests like you would any other Node project, use your local command line to add npm modules, not to mention push your code to a repo such as GitHub. This allows you to implement version control and enables multiple developers to contribute code to the same Gadget project.

Getting Started 

The quickest way to clone your files is to run the following in your terminal:

npx ggt@latest sync ~/gadget/example-app --app=example-app

This will copy example-app's files into your ~/gadget/example-app directory.

Once started, ggt dev will continue to sync files between your app and your local directory. The syncing works in both directions: any file changes in your local directory will be synced back to Gadget, and changes in Gadget will be synced to your local directory.

ggt dev will continue to run in the background until you stop it manually.

Next steps 

Running npx ggt@latest sync ~/gadget/example-app --app=example-app is a great way to get started, but it can be a bit tedious to type over and over again. Thankfully, you can do a few things to make it easier.

Step 1: Install ggt globally

Installing ggt globally is as simple as running the following in your terminal:

yarn global add ggt

npm install --global ggt

You can verify that ggt was properly installed by running ggt --help. Once you have verified that the install was successful, you can use ggt anywhere in your terminal -- no need for npx!

Step 2: Skip the --app flag

ggt dev remembers which app was used to sync a local directory. Therefore, when you sync to the same directory again, you can skip the --app flag.

# After the first sync, the following are identical
ggt dev ~/gadget/example-app
ggt dev ~/gadget/example-app --app=example-app

Step 3: Skip the directory

By default, ggt dev will sync to the directory that you are currently in.

# When you're already inside your local directory, the following are identical
ggt dev
ggt dev .
ggt dev ~/gadget/example-app

There we go! 🎉

We turned npx ggt@latest sync ~/gadget/example-app --app=example-app into a simple ggt dev.

Now, whenever you're ready to start developing your app locally, it's as simple as:

cd ~/gadget/example-app
ggt dev

Resolving conflicts 

If you make changes locally or pull changes down from version control and then start running ggt dev, you might find that you have conflicts. The same file may have been edited locally and in the Gadget app since the last sync was run.

Thankfully, ggt will detect conflicts for you. It will also give you a couple of different options for resolving conflicts:

• Cancel (Ctrl+C): You can choose to cancel the sync operation
• Keep my conflicting changes: Keep your local conflicting changes and overwrite Gadget's.
• Keep Gadget's conflicting changes: Keep Gadget's conflicting changes and overwrite your local ones.

Note that these options will keep the conficting changes for all file conflicts! In the example below, selecting either option will overwrite changes to both routes/GET.js and routes/POST-order.js files.

terminal
$ ggt dev
You have conflicting changes with Gadget

                           You      Gadget
routes/GET.js          ± updated  ± updated
routes/POST-order.js   ± updated  - deleted

? How would you like to resolve these conflicts?
>   Cancel (Ctrl+C)
    Keep my conflicting changes
    Keep Gadget's conflicting changes

If there are changes you want to keep from both your local filesystem and Gadget environment, you will need to port them to your local filesystem or Gadget editor and attempt to sync again. For example, I might port the changes from my Gadget editor over to my local filesystem, restart ggt dev, and notice ggt detects no conflicts and begins watching for file changes as normal.

Autmatically resolving conflicts 

If you always know which conflicting changes you want to keep, you can skip the prompt and automatically choose to keep your desired changes by using the --prefer flag:

terminal
Copy
# automatically keep your local filesystem's conflicting changes
$ ggt dev --prefer=local

# automatically keep Gadget's conflicting changes
$ ggt dev --prefer=gadget

Syncing once 

If you want to sync your local filesystem with your Gadget environment once and not have ggt dev continue watching for changes, you can use the --once flag:

terminal
$ ggt dev --once
→ Sent 12:00:00 PM
routes/GET.js  updated ±

← Received 12:00:00 PM
routes/POST-order.js   updated ±

Done!

The --once flag in combination with --prefer is useful if you want to run ggt dev in a script or CI/CD pipeline and ensure that the sync will not hang waiting for user input.

terminal
Copy
$ ggt dev --once --prefer=local

Ignoring files 

Occasionally, you will want to prevent certain files from being sent to Gadget when you run ggt dev. For instance, you may have files that are only used for local development, such as .eslintrc, or an entire folder like .vscode.

To ignore these files, you can create a .ignore file in the root of your local directory.

.ignore
ignore
Copy
.eslintrc
.vscode

With that in place, ggt dev will no longer send those files up to Gadget when they're changed. The .ignore uses the same semantics as a .gitignore file. Take a look at their docs for more information.

CLI tokens 

Developers can generate CLI tokens per app to serve as secure credentials for CLI access, enabling authorized interactions with CI/CD pipelines, cloud platforms, version control systems, and APIs.

How to generate a CLI token 

1. In the left-hand corner of Gadget click on your app profile menu.

2. From the dropdown select CLI tokens.

3. To generate a new CLI token click Generate token type in the name for this token in the input field and enter.

4. Voila you will now have created a CLI token for use.

Using your CLI token to access a Github Action 

1. Generate a CLI token in Gadget
2. Once you have your CLI token, go to your GitHub repository's settings, then find the Secrets section. Add a new secret named GGT_TOKEN and paste your CLI token as the value. This step ensures that your token is securely stored and accessible in your GitHub Actions workflow.
3. In your Gadget app, create a .github/workflows directory. Inside, you'll create a YAML file for your workflow.
4. In your YAML workflow file, paste the token as shown below in the config steps of your Github Action.

action.yml
yaml
Copy
1name: CI/CD Pipeline
2
3on:
4  push:
5    branches:
6      - main  # or any other branch you want to deploy from
7
8jobs:
9  deploy:
10    steps:
11      - name: Deploy to Gadget Production
12        uses: gadget-inc/ggt-deploy-action@v1
13        with:
14          app: 'gadget-project'
15          environment: 'production'  # Change to the desired environment
16          token: ${{ secrets.GGT_TOKEN }} # Add your CLI token generated from Gadget here
17          allow-issues: 'true'  # Optionally, continue deployment even if there are issues