### Initialize gmailctl

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Run the initial setup process for gmailctl. This guides through Gmail API setup and settings updates.

```bash
gmailctl init
```

--------------------------------

### Install gmailctl using Go

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Install the gmailctl binary from source using the Go toolchain. Ensure your GOPATH is set up correctly and its bin directory is in your PATH.

```go
go install github.com/mbrt/gmailctl/cmd/gmailctl@latest
```

--------------------------------

### Download and Edit Gmail Filters

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Use 'download' to get current filters into a config file, then 'diff' to check, and 'edit' to modify. Recommended for migrating or starting from scratch.

```bash
gmailctl download > ~/.gmailctl/config.jsonnet
gmailctl diff
gmailctl edit
```

--------------------------------

### Install gmailctl on Fedora Linux

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Install gmailctl on Fedora Linux from the official repositories using dnf.

```bash
sudo dnf install gmailctl
```

--------------------------------

### Install gmailctl as a Snap package

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Install gmailctl on Linux distributions that support Snap packages.

```bash
sudo snap install gmailctl
```

--------------------------------

### AST Simplification Example

Source: https://github.com/mbrt/gmailctl/blob/master/AGENTS.md

Illustrates the AST simplification process in the parser layer, showing how nested OR operations are flattened into a single leaf node.

```go
// Before: {or: [{from: "a"}, {from: "b"}]}
// After: Single leaf with Function=FunctionFrom, Args=["a", "b"]
```

--------------------------------

### Install gmailctl with Homebrew

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Install gmailctl on macOS using the Homebrew package manager.

```bash
# Install with Homebrew
brew install gmailctl
```

--------------------------------

### Install gmailctl with Macports

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Install gmailctl on macOS using the Macports package manager.

```bash
# Install with Macports
sudo port install gmailctl
```

--------------------------------

### Example Gmail Filter in Ruby (gmail-britta)

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

This is an example of how a similar filter might be represented in Ruby using the gmail-britta tool. Note the comment indicating it requires a specific master version.

```ruby
#!/usr/bin/env ruby

# NOTE: This file requires the latest master (30/07/2018) of gmail-britta.

```

--------------------------------

### Example of Automatically Generated Labels

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Illustrates the output of `lib.rulesLabels`, showing automatically added labels derived from filter rules, including parent labels, and manually added labels.

```jsonnet
labels: [
  // Automatically added
  { name: 'directed' },
  { name: 'lists' },            // Implied parent label
  { name: 'lists/baz' },
  { name: 'lists/foobar' },
  { name: 'wow' },
  // Manually added
  { name: 'manual-label1' },
  { name: 'priority' },
  { name: 'priority/p1' },
]
```

--------------------------------

### Expanded Reusable Filters

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

This is the expanded version of the previous example, showing how the 'local' variables are substituted directly into the rules. It demonstrates the effective equivalence without using Jsonnet's local variable feature.

```jsonnet
{
  version: 'v1alpha3',
  rules: [
    {
      filter: {
        and: [
          { from: 'foobar' },
          {
            not: {
              or: [
                { to: 'myself@gmail.com' },
                { to: 'myself@yahoo.com' },
              ],
            },
          },
        ],
      },
      actions: {
        delete: true,
      },
    },
    {
      filter: {
        or: [
          { to: 'myself@gmail.com' },
          { to: 'myself@yahoo.com' },
        ],
      },
      actions: {
        labels: ['directed'],
      },
    },
  ],
}
```

--------------------------------

### Combining Filters with Logic Operators (OR, AND, NOT)

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Use logic operators to create complex filter rules. This example marks emails as important if they are from 'foo' OR if they are from the 'bar' mailing list AND not directed to 'baz'.

```jsonnet
{
  version: 'v1alpha3',
  rules: [
    {
      filter: {
        or: [
          { from: 'foo' },
          {
            and: [
              { list: 'bar' },
              { not: { to: 'baz' } },
            ],
          },
        ],
      },
      actions: {
        markImportant: true,
      },
    },
  ],
}
```

--------------------------------

### Reusing Filters with Jsonnet Locals

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Define reusable filter components using Jsonnet's 'local' keyword. This example defines 'toMe' and 'notToMe' filters that are then used in two separate rules.

```jsonnet
local toMe = {
  or: [
    { to: 'myself@gmail.com' },
    { to: 'myself@yahoo.com' },
  ],
};
local notToMe = { not: toMe };

{
  version: 'v1alpha3',
  rules: [
    {
      filter: {
        and: [
          { from: 'foobar' },
          notToMe,
        ],
      },
      actions: {
        delete: true,
      },
    },
    {
      filter: toMe,
      actions: {
        labels: ['directed'],
      },
    },
  ],
}
```

--------------------------------

### Gmail Filter with Query Operator

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

This example demonstrates using the 'query' operator to pass a complex search string directly to the Gmail filter. It's useful for advanced searches not covered by standard operators.

```jsonnet
{
      filter: {
        query: 'dinner AROUND 5 friday has:spreadsheet',
      },
      actions: {
        delete: true,
      },
    }
```

--------------------------------

### Nested Jsonnet Filter Configuration

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Configure complex Gmail filtering rules with nested 'and', 'or', and 'not' expressions using Jsonnet. This example filters emails sent to 'me' from a specific friend, excluding spam.

```jsonnet
local me = 'pippo@gmail.com';
local spam = {
  or: [
    { from: 'foo@gmail.com' },
    { from: 'bar@hotmail.com' },
    { subject: 'buy this' },
    { subject: 'buy that' },
  ],
};
{
  version: 'v1alpha3',
  rules: [
    {
      filter: {
        and: [
          { to: me },
          { from: 'friend@mail.com' },
          { not: spam },
        ],
      },
      actions: { delete: true },
    },
  ],
}
```

--------------------------------

### Error Handling with internal/errors

Source: https://github.com/mbrt/gmailctl/blob/master/AGENTS.md

Demonstrates using the internal/errors package for wrapping errors with causes and adding user-facing details.

```go
errors.WithCause(err, ErrNotFound)  // Wraps with sentinel
errors.WithDetails(err, "help text")  // Adds user-facing details
```

--------------------------------

### Build and Test gmailctl

Source: https://github.com/mbrt/gmailctl/blob/master/AGENTS.md

Commands for building the gmailctl binary, running unit tests, executing integration tests with golden file updates, and generating coverage reports.

```bash
go build ./cmd/gmailctl
```

```bash
go test ./...
```

```bash
go test -v -update ./...
```

```bash
./hack/coverage.sh
```

--------------------------------

### List of Available gmailctl Commands

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

This is a list of all available commands for the gmailctl tool. Use 'gmailctl help' for more details on any specific command.

```bash
  apply       Apply a configuration file to Gmail settings
  debug       Shows an annotated version of the configuration
  diff        Shows a diff between the local configuration and Gmail settings
  download    Download filters from Gmail to a local config file
  edit        Edit the configuration and apply it to Gmail
  export      Export filters into the Gmail XML format
  help        Help about any command
  init        Initialize the Gmail configuration
  test        Execute config tests
```

--------------------------------

### Chaining Filters with Utility Library

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Demonstrates how to use the `chainFilters` function from the `gmailctl.libsonnet` library to create a sequence of filters where subsequent filters are only applied if preceding ones do not match. This simulates if-else logic.

```jsonnet
// Import the standard library
local lib = import 'gmailctl.libsonnet';

local favourite = {
  or: [
    { from: 'foo@bar.com' },
    { from: 'baz@bar.com' },
    { list: 'wow@list.com' },
  ],
};

{
  version: 'v1alpha3',
  rules: [           // ... Other filters applied in any order
         ]

         // And a chain of filters
         + lib.chainFilters([
           // All directed emails will be marked as important
           {
             filter: { to: 'myself@gmail.com' },
             actions: { markImportant: true },
           },
           // Otherwise, if they come from interesting senders, apply a label
           {
             filter: favourite,
             actions: { labels: ['interesting'] },
           },
           // Otherwise, if they are directed to my spam alias, archive
           {
             filter: { to: 'myself+spam@gmail.com' },
             actions: { archive: true },
           },
         ]),
}
```

--------------------------------

### Download and Edit Configuration

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Download the current gmailctl configuration to a file and then edit it. This is a useful workflow for updating your config to include existing labels.

```bash
$ gmailctl download > /tmp/cfg.jsonnet
$ gmailctl edit
```

--------------------------------

### Initialize and Reset Credentials

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Commands to reset and re-initialize gmailctl credentials. This is often necessary when updating scopes or re-creating credentials for label management.

```bash
$ gmailctl init --reset
$ gmailctl init
```

--------------------------------

### Basic Test Configuration Structure

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Defines the top-level structure for adding tests to a gmailctl configuration file. The 'tests' field accepts an array of test objects.

```jsonnet
{
  version: 'v1alpha3',
  rules: [ /* ... */ ],
  tests: [
    // you tests here.
  ],
}
```

--------------------------------

### Import and Use Jsonnet Library in Config

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Import a Jsonnet library (e.g., `spam.libjsonnet`) into a main configuration file (`config.jsonnet`) to apply reusable filter logic. This allows for cleaner and more organized filter management.

```jsonnet
local spam_filter = import 'spam.libjsonnet';
{
  version: 'v1alpha3',
  rules: [
    {
      filter: spam_filter,
      actions: { delete: true },
    },
  ],
}
```

--------------------------------

### Replace Old Config with New

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Once you confirm the new Jsonnet configuration is correct, use these commands to replace the old YAML config.

```bash
$ mv /tmp/gmailctl-config.jsonnet ~/.gmailctl/config.jsonnet
$ rm ~/.gmailctl/config.yaml
```

--------------------------------

### Bash Aliases for Multiple Gmail Accounts

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Set up bash aliases to manage multiple Gmail accounts with different configurations. Each alias points to the `gmailctl` command with a specific configuration file path.

```bash
alias gmailctlu1='gmailctl --config=$HOME/.gmailctlu1'
alias gmailctlu2='gmailctl --config=$HOME/.gmailctlu2'
```

--------------------------------

### Configure xdg-mime for config file editor

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Configure xdg-mime to associate a text editor (e.g., vim) with the config file type for gmailctl.

```bash
xdg-mime default vim.desktop text/x-csrc
```

--------------------------------

### Migrate YAML Config to Jsonnet

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Use this command to convert older YAML configurations to the latest Jsonnet format. Adjust the path if your config is not in the default location.

```bash
$ go run github.com/mbrt/gmailctl/cmd/gmailctl-config-migrate \
    ~/.gmailct/config.yaml > /tmp/gmailctl-config.jsonnet
```

--------------------------------

### Test Object Structure

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Outlines the structure of a single test object, including its name, the messages to test against, and the expected actions.

```jsonnet
{
  // Reported when the test fails.
  name: "the name of the test",
  // A list of messages to test against.
  messages: [
    { /* message object */ },
    // ... more messages
  ],
  // The actions that should be applied to the messages, according the config.
  actions: {
    // Same as the Actions object in the filters.
  },
}
```

--------------------------------

### Diff Jsonnet Config

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

After migrating your config to Jsonnet, use this command to check for errors and compare it with your remote filters.

```bash
$ gmailctl diff -f /tmp/gmailctl-config.jsonnet
```

--------------------------------

### Automatically Generate Labels with rulesLabels

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Utilize the `lib.rulesLabels` function from the gmailctl library to automatically generate a list of labels based on filters defined in your rules. This avoids manual label definition and ensures all referenced labels are included.

```jsonnet
local lib = import 'gmailctl.libsonnet';
local rules = [
  {
    filter: { to: 'myself@gmail.com' },
    actions: { labels: ['directed'] },
  },
  {
    filter: { from: 'foobar' },
    actions: { labels: ['lists/foobar'] },
  },
  {
    filter: { list: 'baz' },
    actions: { labels: ['lists/baz', 'wow'] },
  },
];

// the config
{
  version: 'v1alpha3',
  rules: rules,
  labels: lib.rulesLabels(rules) + [{ name: l } for l in [
    'manual-label1',
    'priority',
    'priority/p1',
  ]],
}
```

--------------------------------

### Use DirectlyTo Function with Gmailctl Library

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Import the gmailctl library and use the `directlyTo` function to create filters for emails addressed specifically to you. Requires importing the library and defining the recipient.

```jsonnet
// Import the standard library
local lib = import 'gmailctl.libsonnet';
local me = 'pippo@gmail.com';
{
  version: 'v1alpha3',
  rules: [
    {
      filter: lib.directlyTo(me),
      actions: { markImportant: true },
    },
  ],
}
```

--------------------------------

### Correct Message Formatting in Tests

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Shows the correct way to structure the 'messages' array within a test object when a single message has multiple recipients or properties. Each message object should contain all its properties.

```jsonnet
{
  // ...
  tests: [
    messages: [
      {
        from: "foobar",
        to: "me",
      },
    ],
    actions: {
      // ...
    },
  ],
}
```

--------------------------------

### Apply Actions to Emails

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Configure actions to be applied to emails that pass a rule's filter. This includes archiving, deleting, marking as read, starring, marking as spam (not supported by Gmail to set to true), marking as important, categorizing, and applying labels.

```jsonnet
{
  version: 'v1alpha3',
  rules: [
    {
      filter: { from: 'love@gmail.com' },
      actions: {
        markImportant: true,
        category: 'personal',
        labels: ['family', 'P1'],
      },
    },
  ],
}
```

--------------------------------

### Basic Jsonnet Configuration for Gmail Filters

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

This Jsonnet configuration defines Gmail filter rules. It includes local variables for reuse and specifies filter conditions and actions like archiving and labeling.

```jsonnet
// Local variables help reuse config fragments
local me = {
  or: [
    { to: 'pippo@gmail.com' },
    { to: 'pippo@hotmail.com' },
  ],
};

// The exported configuration starts here
{
  version: 'v1alpha3',
  // Optional author information (used in exports).
  author: {
    name: 'Pippo Pluto',
    email: 'pippo@gmail.com'
  },
  rules: [
    {
      filter: {
        and: [
          { list: 'geeks@newsletter.com' },
          { not: me },  // Reference to the local variable 'me'
        ],
      },
      actions: {
        archive: true,
        labels: ['news'],
      },
    },
  ],
}
```

--------------------------------

### Define Spam Filter in Jsonnet Library

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Define a reusable spam filter configuration in a separate Jsonnet file (`spam.libjsonnet`). This promotes modularity and reusability of filter definitions.

```jsonnet
{
  or: [
    { from: 'foo@gmail.com' },
    { from: 'bar@hotmail.com' },
    { subject: 'buy this' },
    { subject: 'buy that' },
  ],
}
```

--------------------------------

### Manage Labels with gmailctl

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Configure label management within gmailctl. This section allows for the creation and management of labels. Ensure your Google API scopes include 'https://www.googleapis.com/auth/gmail.labels' for this functionality.

```jsonnet
{
  version: 'v1alpha3',
  // optional
  labels: [
    { name: 'family' },
    { name: 'friends' },
  ],
  rules: [
    {
      filter: { from: 'love@gmail.com' },
      actions: {
        labels: ['family'],
      },
    },
  ],
}
```

--------------------------------

### Manage Label Colors

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Optionally enforce label colors by specifying background and text colors. If not specified, the existing label color will be preserved. Supported colors can be found in the Gmail API documentation.

```jsonnet
{
  version: 'v1alpha3',
  labels: [
    {
      name: 'family',
      color: {
        background: "#fad165",
        text: "#000000",
      },
    },
  ],
  rules: [ // ...
  ],
}
```

--------------------------------

### Set EDITOR environment variable in Windows CMD

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Configure the EDITOR environment variable in Windows Command Prompt to use VS Code for editing config files.

```cmd
//cmd
set "EDITOR=code --wait"
```

--------------------------------

### Refresh Expired Auth Token

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

If you encounter 'invalid_grant' errors, your auth token may have expired. Try refreshing it using this command.

```bash
$ gmailctl init --refresh-expired
```

--------------------------------

### Define Local Variable for Email Address

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Use a local variable to define your email address for easier reuse in filter configurations. This improves readability and maintainability.

```jsonnet
local me = 'myemail@gmail.com';

{
  version: 'v1alpha3',
  rules: [
    {
      filter: { to: me },
      actions: {
        markImportant: true,
      },
    },
  ],
}
```

--------------------------------

### Basic Gmail Filter with Subject Search

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Use this snippet to mark emails with a specific subject as important. It defines a rule with a subject filter and an action to mark as important.

```jsonnet
{
  version: 'v1alpha3',
  rules: [
    {
      filter: { subject: 'important mail' },
      actions: {
        markImportant: true,
      },
    },
    {
      filter: {
        query: 'dinner AROUND 5 friday has:spreadsheet',
      },
      actions: {
        delete: true,
      },
    },
  ],
}
```

--------------------------------

### Define Spam Filters in Ruby

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Use this Ruby code to define and generate Gmail filters for spam emails based on sender addresses and subjects. Ensure SPAM_EMAILS and SPAM_SUBJECTS are correctly populated.

```ruby
require 'rubygems'
require 'gmail-britta'

SPAM_EMAILS = %w{foo@gmail.com bar@hotmail.com}
SPAM_SUBJECTS = ['"buy this"', '"buy my awesome product"']

puts(GmailBritta.filterset(:me => MY_EMAILS) do
       # Spam
       filter {
         has [{:or => "from:(#{SPAM_EMAILS.join("|")})"}]
         delete_it
       }
       filter {
         has [{:or => "subject:(#{SPAM_SUBJECTS.join("|")})"}]
         delete_it
       }
     end.generate)
```

--------------------------------

### Handle Escaped Expressions in Jsonnet

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

When 'download' cannot map a filter to native gmailctl expressions, it uses 'isEscaped: true'. Manually port these to regular operators to avoid unexpected results.

```jsonnet
{
  from: "{foo bar baz}",
  isEscaped: true,
}
```

```jsonnet
{
  or: [
    {from: "foo"},
    {from: "bar"},
    {from: "baz"},
  ],
}
```

--------------------------------

### Incorrect Message Array Formatting in Tests

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Illustrates a common mistake where multiple message objects are placed directly in the 'messages' array, resulting in them being treated as separate messages rather than a single, multi-recipient message.

```jsonnet
{
  // ...
  tests: [
    messages: [
      { from: "foobar" },
      { to: ["me"] },
    ],
    actions: {
      // ...
    },
  ],
}
```

--------------------------------

### Set EDITOR environment variable in Windows PowerShell

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Configure the EDITOR environment variable in Windows PowerShell to use VS Code for editing config files.

```powershell
//powershell
setx EDITOR "code --wait"
```

--------------------------------

### Define DirectlyTo Recipient Function

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

Define a function to match emails sent directly to you, excluding CC and BCC recipients. This function ensures emails are only in the TO field.

```jsonnet
local directlyTo(recipient) = {
  and: [
    { to: recipient },
    { not: { cc: recipient } },
    { not: { bcc: recipient } },
  ],
};
```

--------------------------------

### Define Gmail Filter Rules in Jsonnet

Source: https://github.com/mbrt/gmailctl/blob/master/README.md

This Jsonnet code defines a set of rules for Gmail filters, including a rule to delete emails matching specific 'from' addresses or subjects.

```jsonnet
local spam = {
  or: [
    { from: 'pippo@gmail.com' },
    { from: 'pippo@hotmail.com' },
    { subject: 'buy this' },
    { subject: 'buy that' },
  ],
};
{
  version: 'v1alpha3',
  rules: [
    {
      filter: spam,
      actions: { delete: true },
    },
  ],
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.