# gactions user guide

This guide shows you how to use the gactions command line interface (CLI) tool
in common usage scenarios. For information on building Actions end-to-end, see
the Conversational Actions [Build](https://developers.google.com/assistant/conversational/build) documentation.

> [!NOTE]
> **Tip:** To see more information when running commands, use the `--verbose` flag.

## Project synchronization

When using the Actions SDK, gactions is your tool to synchronize Action projects
between the Actions console and your local file system.

`gactions pull` operations export a project from the Actions console to your
local file system, and `gactions push` operations push a project from your local
file system to the Actions console.

### Download Actions from Actions console

Run `gactions pull` to copy the configuration of an Actions project to the local
file system.

The `project-id` of the project you want to copy can be passed on the command
line, or written in the `settings/settings.yaml` file. If both are present, the
CLI gives precedence to the value passed as an option.

    mkdir -p myAction/sdk
    cd myAction/sdk
    gactions pull --project-id my-project-id
    Pulling your project files from Draft for a project id: "my-project-id"
    ✔ Done. You should see the files written in path/to/myAction/sdk
    ls -l
    total 8
    drwxr-x---  3 user  primarygroup   96 May  7 10:00 actions
    drwxr-x---  4 user  primarygroup  128 May  7 10:00 custom
    -rw-r---  1 user  primarygroup   15 May  7 10:00 manifest.yaml
    drwxr-x---  3 user  primarygroup   96 May  7 10:00 settings
    vi settings/settings.yaml
    // change projectId to "my-other-project-id"
    gactions pull
    Pulling your project files from Draft for a project id: "my-other-project-id"
    path/to/myAction/sdk/manifest.yaml already exists. Would you like to overwrite it?. [y/n]
    ...
    ✔ Done. You should see the files written in path/to/myAction/sdk

The code snippet above shows how to pull an Action from project draft. It's
also possible to pull from a specific version of your Action. A version
represents a submitted copy of your Actions project, which could be deployed to a
release channel.

The `--version-id` flag specifies which version to pull.

    mkdir -p myAction/sdk
    cd myAction/sdk
    gactions pull --project-id my-project-id --version-id my-version-id
    Pulling version "my-version-id" of the project "my-project-id" from Actions Console...
    ✔ Done. You should see the files written in path/to/myAction/sdk
    ls -l
    total 8
    drwxr-x---  3 user  primarygroup   96 May  7 10:00 actions
    drwxr-x---  4 user  primarygroup  128 May  7 10:00 custom
    -rw-r---  1 user  primarygroup   15 May  7 10:00 manifest.yaml
    drwxr-x---  3 user  primarygroup   96 May  7 10:00 settings

Use the `--force` flag if you want to overwrite local copies of file without
being asked for confirmation. Use the `--clean` flag to remove any of the local
files that are not present in the remote Draft or Version. Use them together to get an
exact copy of the Actions console project.

    touch local_file.txt
    gactions pull --force
    Pulling your project files from Draft for a project id: "my-project-id"
    [WARNING] 2020/05/07 17:34:32 path/to/myAction/sdk/local_file.txt is not present in the draft of your Action. To remove, run pull with --clean flag.
    ✔ Done. You should see the files written in path/to/myAction/sdk
    gactions pull --force --clean
    Pulling your project files from Draft for a project id: "my-project-id"
    [WARNING] 2020/05/07 17:43:44 path/to/myAction/sdk/local_file.txt is not present in the draft of your Action. Removing path/to/myAction/sdk/local_file.txt.
    ✔ Done. You should see the files written in path/to/myAction/sdk

### Push Actions to Actions console project draft

Run `gactions push` to push changes from the local file system to the Draft of
your Action in the console. This process can be useful during development to
view your changes reflected in the Actions console, without affecting the
version that's served for testing.

    gactions push
    Pushing your project files to your Actions console draft for a project id: "my-project-id". This may take a few minutes.
    Sending configuration files
    Waiting for server to respond.
    ✔ Done. You can now navigate to the Actions Console: https://console.actions.google.com/project/my-project-id/overview to view your project. If you want to test your changes in the simulator, run "gactions deploy preview"

### Import an existing project from a source code management system

If you want to work on an existing project from a revision in a version control
system:

1. Check out the target revision (depends on the system).
2. Replace the value of `projectId` in the project's `settings.yaml`.
3. Optionally, run `gactions push` to copy the local configuration files to the Actions project.

    git clone https://github.com/my/repo.git
    Cloning into 'repo'...
    remote: Enumerating objects: 10, done.
    remote: Counting objects: 100% (10/10), done.
    remote: Compressing objects: 100% (9/9), done.
    remote: Total 51 (delta 3), reused 3 (delta 1), pack-reused 41
    Receiving objects: 100% (51/51), 36.86 KiB | 3.69 MiB/s, done.
    Resolving deltas: 100% (11/11), done.
    cd repo/sdk/
    vi settings/settings.yaml
    // change the value of `projectId`
    gactions push

### Listing versions

Run `gactions versions list` to view details about versions of your Action.
To learn more about version statuses, refer to the reference for [State](https://developers.google.com/assistant/actionssdk/reference/rest/Shared.Types/State).

    gactions versions list
    Version         Status          Last Modified By        Modified On     
    1           Created     your-email@your-domain.com  2020-09-28 20:22:04

If the status of your deployment says "Creation failed", you can get more details
about it in the Console under the "Release" section.

## Deploy projects

The `gactions deploy` command lets you deploy your project to test in the
Actions simulator or deploy to alpha/beta/production release channels.

> [!NOTE]
> **Note:** If you are using inline fulfillment in your Actions project, you must have a billing profile enabled before running the `gactions deploy` command. If you don't set up billing, you might run into errors deploying that can take 5-10 minutes to resolve before you can deploy again.

### Preview in simulator

Run `gactions deploy preview` to deploy your Action to "preview", which lets
you test your Action in the console, without actually updating the version of
your Action project or impacting other developers. In other words, none of the
changes you make in your local file system are propagated to deployed versions
of your Actions project, but they are available to test on a preview version.

> [!NOTE]
> **Note:** This process requires at least the main invocation (`custom/global/actions.intent.MAIN.yaml`) to be defined.

    gactions deploy preview
    Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
    Sending configuration files
    Waiting for server to respond.
    ✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview

### Create releases

Run `gactions deploy` to create version releases for alpha/beta/prod channels
that you can manage through the **Deploy** section in the Actions console.
Use it to test release candidates of your Action with your alpha and/or beta
channels, and move the release candidate to production when you're satisfied
with the feedback.

    gactions deploy alpha
    Deploying your project files to a actions.channels.Alpha channel for a project id: "my-project-id"
    Sending configuration files
    Waiting for server to respond.
    ✔ Done. Your Action was deployed to actions.channels.Alpha channel. You can check status of deployment in the Actions Console.

### Listing release channels

Run `gactions release-channels list` to view details about release channels
for your Action. You can use this command to identify the version
deployed or pending to each channel.

    gactions release-channels list
    Release Channel             Current Version             Pending Version
    alpha                   1                     N/A

## Account linking

The `gactions encrypt` and `gactions decrypt` commands let you administer OAuth2
client secrets. These commands are specific to [account linking](https://developers.google.com/assistant/identity).

### Encrypt OAuth2 account linking client secrets

Run `gactions encrypt` to safely add client secrets for auth code OAuth2 account
linking flows, or to encrypt existing secrets with a new encryption key.

    gactions encrypt
    Write your secret: *********************
    Encrypting your client secret
    path/to/myAction/sdk/settings/accountLinkingSecret.yaml already exists. Would you like to overwrite it?. [y/n]
    y
    ✔ Done. Encrypted secret was written to path/to/myAction/sdk/settings/accountLinkingSecret.yaml

### Access plain text value of encrypted account linking secrets.

Run `gactions decrypt` if you need to temporarily access the plain text value of
the project's secret. The command prints the value to a text file of your choice.
We recommend the destination file to be outside the root folder of the project,
to avoid any accidental leak of the plain text value.

    gactions decrypt ../../burn_after_read.txt
    Decrypting your client secret
    ✔ Done. Check path/above/myActions/burn_after_read.txt to find decrypted client secret.
    vi ../../burn_after_read.txt
    rm ../../burn_after_read.txt