magitrickle is a command-line tool for managing and configuring MagiTrickle through a UNIX socket.

1. Overview
2. Installation
3. How It Works
4. CLI Usage
   • System Commands
   • Group Commands
   • Rule Commands
5. Examples
6. Tips and Troubleshooting
7. License

MagiTrickle CLI helps you interact with MagiTrickle's backend via:

• Groups – logical containers for traffic or domain matching
• Rules – define the matching patterns or IP/domain restrictions
• System hooks – advanced capabilities such as netfilterd, interface listing, and saving config

The CLI communicates over a UNIX socket to send HTTP requests to the MagiTrickle API.
Commands are structured in a tree-like format under the single executable magitrickle:

• system
  – For system-level operations (hooks, listing interfaces, saving configs).
• group
  – Create, list, update, and delete groups.
• rule
  – Create, list, update, and delete rules in a specified group.

Will be added soon...

You can see the full list of commands by typing:

magitrickle --help

Similarly, each subcommand supports --help to list detailed usage:

magitrickle group --help
magitrickle rule --help
magitrickle system --help

magitrickle group list

Output:

Groups:
 - ID: 182f11dd
   Name: Debug
   Interface: singtun-ru1
   Enabled: true
   Color: #791a3e

magitrickle group create \
    --name="TestGroup" \
    --interface="br1" \
    --enable=true \
    --color="#abc123"

Output:

Group created successfully
 ID: e89c1f15
 Name: TestGroup
 Interface: br1
 Enabled: true
 Color: #abc123

magitrickle rule create e89c1f15 \
    --name="BlockExampleDomain" \
    --type="domain" \
    --rule="example.com" \
    --enable=true \
    --save

Output:

Rule created successfully:
 ID: 4c40d238 | Name: BlockExampleDomain | Type: domain | Rule: example.com | Enabled: true

magitrickle group update e89c1f15 \
    --name="NewGroupName" \
    --enable=false \
    --save

Output:

Group updated successfully
 ID: e89c1f15
 Name: NewGroupName
 Interface: br1
 Enabled: false
 Color: #abc123

Configuration is immediately persisted due to --save.

magitrickle system interfaces

Example output:

Available Interfaces:
  - br0
  - br1
  - eth0
  - wlan0

magitrickle system save-config

Output:

Configuration saved successfully

1. Make sure the MagiTrickle backend is running.
   The CLI will fail to connect if the UNIX socket (e.g., /var/run/magitrickle.sock) is not accessible or if the magitrickled is offline.

2. Use --help often.
   Each subcommand has detailed flags and usage info.

3. Persisting changes with --save.
   When you create, update, or delete a group/rule, you can optionally add --save to immediately persist those changes to the server configuration. Otherwise, you can always run:

   magitrickle system save-config

   afterwards to commit all outstanding changes.