Freshdesk CLI

A fast, lightweight command-line interface for Freshdesk built with .NET 9 and AOT compilation.

Features

🚀 Fast & Lightweight - Native AOT compilation for instant startup and small binary size (~3-5MB)
🔒 Read-Only Mode - Safe exploration mode that prevents accidental modifications
📊 Multiple Output Formats - Table (human-readable), JSON, CSV, XML, and Markdown formats
📤 Export Functionality - Export tickets and conversations to multiple formats
📥 Bulk Downloads - Download all attachments from tickets with progress indicators
🔐 Secure Credential Storage - File-based with proper permissions and environment variable support
🌍 Cross-Platform - Works on Linux, macOS, and Windows
⚡ Rate Limit Handling - Automatic retry with exponential backoff
📈 Progress Indicators - Visual progress bars for long-running operations

Installation

Quick Install (Recommended)

Linux/macOS:

curl -sSL https://raw.githubusercontent.com/Aaronontheweb/freshdesk-cli/dev/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Aaronontheweb/freshdesk-cli/dev/install.ps1 | iex

Install Beta Releases:

curl -sSL https://raw.githubusercontent.com/Aaronontheweb/freshdesk-cli/dev/install.sh | bash -s -- --beta

From Source

# Clone the repository
git clone https://github.com/Aaronontheweb/freshdesk-cli.git
cd freshdesk-cli

# Build and install globally (Linux/macOS)
dotnet publish src/FreshdeskCLI -c Release -r linux-x64 /p:PublishAot=true
sudo cp ./publish/linux-x64/freshdesk /usr/local/bin/

# Or run directly
dotnet run --project src/FreshdeskCLI -- --help

Pre-built Binaries

Download the latest release for your platform from the Releases page.

Uninstallation

Remove Freshdesk CLI:

curl -sSL https://raw.githubusercontent.com/Aaronontheweb/freshdesk-cli/dev/install.sh | bash -s -- --uninstall

This will:

Remove the freshdesk binary from your installation directory
Optionally remove the configuration directory (~/.freshdesk) if you choose
Optionally remove the installation directory if it becomes empty

Configuration

Initial Setup

# Configure with your Freshdesk credentials
freshdesk config set --domain yourcompany --api-key your_api_key_here

# Test the connection
freshdesk config test

# View current configuration
freshdesk config get

Environment Variables

You can also use environment variables (useful for CI/CD):

export FRESHDESK_API_KEY=your_api_key_here
export FRESHDESK_DOMAIN=yourcompany

Configuration File Location

Configuration is stored at ~/.freshdesk/config.json with secure file permissions (user-only on Unix systems).

Tab Completion

The CLI supports tab completion for bash, zsh, and PowerShell. This feature dynamically generates completion scripts based on the current command structure, ensuring completions are always up-to-date.

Installation

Auto-detect and install for current shell:

freshdesk install-completion

Install for specific shell:

freshdesk install-completion bash       # For Bash
freshdesk install-completion zsh        # For Zsh  
freshdesk install-completion powershell # For PowerShell

Activation

After installation, activate the completion:

Bash:

source ~/.bashrc

Zsh:

source ~/.zshrc

PowerShell:

. $PROFILE

Features

Complete commands and subcommands (e.g., freshdesk ti<TAB> → freshdesk ticket)
Complete options and flags (e.g., freshdesk ticket list --st<TAB> → freshdesk ticket list --status)
Auto-complete enum values (e.g., --status <TAB> shows open, pending, resolved, closed)
File path completion for --output and --file options
Automatically stays in sync with command structure updates

Usage

Read-Only Mode

Add --read-only or -ro to any command to prevent write operations:

# Safe exploration - no accidental changes
freshdesk --read-only ticket list
freshdesk --read-only ticket get 123

Ticket Operations

List Tickets

# List tickets (default format: table)
freshdesk ticket list

# Filter by status
freshdesk ticket list --status open
freshdesk ticket list --status pending

# Filter by customer email
freshdesk ticket list --email [email protected]
freshdesk ticket list --customer [email protected]

# Combine filters
freshdesk ticket list --status open --email [email protected]

# With pagination
freshdesk ticket list --page 2 --limit 50

# Export as JSON
freshdesk ticket list --format json

# Export as CSV
freshdesk ticket list --format csv > tickets.csv

Get Ticket Details

# View ticket details
freshdesk ticket get 123

# Get as JSON
freshdesk ticket get 123 --format json

Create Ticket

# Create a new ticket
freshdesk ticket create \
  --subject "Bug in login page" \
  --email "[email protected]" \
  --description "Cannot login with valid credentials" \
  --priority high

Update Ticket

# Update ticket status and priority
freshdesk ticket update 123 --status resolved --priority low

Search Tickets

# Search tickets by text query
freshdesk ticket search "login issue"
freshdesk ticket search --query "database error"

# Search with filters
freshdesk ticket search --status open --priority high
freshdesk ticket search --email [email protected]
freshdesk ticket search --customer [email protected]

# Combine text search with filters
freshdesk ticket search "login" --status open --priority high

# Export search results
freshdesk ticket search --status open --format json
freshdesk ticket search --email [email protected] --format csv

Reply to Tickets

# Reply with message directly
freshdesk ticket reply 123 --message "Thank you for your inquiry. We're looking into this."

# Reply from file
freshdesk ticket reply 123 --file response.txt

# Interactive reply (will prompt for message)
freshdesk ticket reply 123

Add Internal Notes

# Add internal note directly
freshdesk ticket note 123 --message "Customer has premium support, prioritize this."

# Add note from file
freshdesk ticket note 123 --file internal-notes.txt

# Interactive note (will prompt)
freshdesk ticket note 123

Export Operations

# Export multiple tickets to JSON
freshdesk export tickets --output tickets.json --format json

# Export with filters
freshdesk export tickets --status open --output open_tickets.json
freshdesk export tickets --priority high --output high_priority.json
freshdesk export tickets --email [email protected] --output johns_tickets.json

# Combine multiple filters
freshdesk export tickets --status open --priority high --output urgent.json

# Export to CSV
freshdesk export tickets --format csv --output tickets.csv

# Export to XML
freshdesk export tickets --format xml --output tickets.xml

# Export with conversations included (JSON only)
freshdesk export tickets --format json --output tickets_full.json --include-conversations

# Limit number of tickets exported
freshdesk export tickets --limit 100 --output first_100.json

# Export single ticket to Markdown
freshdesk export ticket 123 --format markdown --output ticket_123.md

# Export single ticket with conversations
freshdesk export ticket 123 --format json --output ticket_123.json --include-conversations

Attachment Operations

List Attachments

# List all attachments for a ticket
freshdesk attachment list 123

Download Attachment

# Download an attachment
freshdesk attachment download 123 456789

# Download with custom output path
freshdesk attachment download 123 456789 --output /path/to/save.pdf

# Download all attachments from a ticket
freshdesk attachment download-all 123 --output-dir ./attachments/

# Bulk download with progress indicator
freshdesk attachment download-all 123 --output-dir ./downloads/ --show-progress

Upload Attachment

# Upload a file to a ticket
freshdesk attachment upload 123 /path/to/file.pdf

# Upload with custom filename
freshdesk attachment upload 123 /path/to/file.pdf --name "Report_2024.pdf"

Output Formats

All list and get commands support multiple output formats:

table (default) - Human-readable table format
json - Machine-readable JSON
csv - Excel-compatible CSV

Example:

freshdesk ticket list --format json | jq '.[] | {id, subject, status}'

Command Reference

Global Options

Option	Short	Description
`--help`	`-h`	Show help information
`--version`	`-v`	Show version information
`--read-only`	`-ro`	Run in read-only mode (blocks all write operations)

Config Commands

Command	Description
`config set`	Set configuration values
`config get`	Display current configuration
`config test`	Test connection to Freshdesk API

Ticket Commands

Command	Description
`ticket list`	List tickets with pagination
`ticket get <id>`	Get ticket details
`ticket create`	Create a new ticket
`ticket update <id>`	Update ticket status/priority
`ticket search <query>`	Search tickets
`ticket reply <id>`	Reply to a ticket
`ticket note <id>`	Add internal note to a ticket
`ticket export`	Export tickets to JSON/CSV/XML/Markdown

Attachment Commands

Command	Description
`attachment list <ticket-id>`	List attachments for a ticket
`attachment download <ticket-id> <attachment-id>`	Download an attachment
`attachment download-all <ticket-id>`	Download all attachments from a ticket
`attachment upload <ticket-id> <file>`	Upload file to ticket

Examples

Daily Operations

# Morning ticket review
freshdesk --read-only ticket list --format table

# Export yesterday's tickets
freshdesk ticket list --format csv > daily_tickets.csv

# Quick status update
freshdesk ticket update 456 --status resolved

Automation

# Check for high priority tickets
freshdesk ticket list --format json | \
  jq '.[] | select(.priority == "High") | {id, subject}'

# Count open tickets
freshdesk ticket list --format json | \
  jq '[.[] | select(.status == "Open")] | length'

Safe Exploration

# Always use read-only mode when exploring
alias fd-safe='freshdesk --read-only'

fd-safe ticket list
fd-safe ticket get 789

Building from Source

Prerequisites

.NET 9 SDK or later
Git

Build Commands

# Clone repository
git clone https://github.com/Aaronontheweb/freshdesk-cli.git
cd freshdesk-cli

# Run tests
dotnet test

# Build for current platform
dotnet build -c Release

# Build with AOT for production (Linux)
dotnet publish src/FreshdeskCLI -c Release -r linux-x64 /p:PublishAot=true

# Build for other platforms
dotnet publish src/FreshdeskCLI -c Release -r win-x64 /p:PublishAot=true
dotnet publish src/FreshdeskCLI -c Release -r osx-x64 /p:PublishAot=true
dotnet publish src/FreshdeskCLI -c Release -r osx-arm64 /p:PublishAot=true

# Test AOT compatibility
dotnet run --project src/FreshdeskCLI -- --test-aot

Supported Platforms

linux-x64 - Linux 64-bit
linux-arm64 - Linux ARM 64-bit
win-x64 - Windows 64-bit
osx-x64 - macOS Intel
osx-arm64 - macOS Apple Silicon

Architecture

AOT Compilation - Native ahead-of-time compilation for fast startup and small binaries
Source Generators - Zero-reflection JSON serialization for AOT compatibility
Reactive Rate Limiting - Handles API rate limits gracefully with automatic retry
Secure Storage - Credentials stored with proper file permissions

Contributing

Contributions are welcome! Please follow these guidelines:

Development Guidelines

Maintain AOT compatibility - no reflection
Keep binary size under 15MB
Follow existing code style
Add tests for new features
Update documentation

Pull Request Process

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Troubleshooting

Common Issues

Authentication Failed

# Check your API key and domain
freshdesk config get
freshdesk config test

Rate Limited The CLI automatically handles rate limits with exponential backoff. If you consistently hit limits, consider reducing request frequency.

Permission Denied

# Ensure proper permissions on config directory
chmod 700 ~/.freshdesk
chmod 600 ~/.freshdesk/config.json

Binary Not Found

# Ensure the binary is in your PATH
echo $PATH
# Or use full path
/usr/local/bin/freshdesk --version

Performance

Startup Time: < 50ms (native AOT)
Binary Size: ~3-5MB (platform dependent)
Memory Usage: < 20MB typical
Rate Limiting: Automatic with exponential backoff

Security

API keys are never logged or displayed in full
Configuration files use secure permissions (600 on Unix)
Environment variables supported for CI/CD
Read-only mode for safe exploration

Roadmap

License

Apache License 2.0 - see LICENSE file for details.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Acknowledgments

Built with ❤️ using:

Author

Created with ❤️ by Aaron Stannard - https://aaronstannard.com/

GitHub: @Aaronontheweb

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.config		.config
.github		.github
docs		docs
scripts		scripts
src/FreshdeskCLI		src/FreshdeskCLI
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Directory.Build.props		Directory.Build.props
Directory.Packages.props		Directory.Packages.props
FreshDeskCli.slnx		FreshDeskCli.slnx
IMPLEMENTATION_PLAN.md		IMPLEMENTATION_PLAN.md
LICENSE		LICENSE
NOTICE		NOTICE
NuGet.Config		NuGet.Config
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
build.ps1		build.ps1
coverlet.runsettings		coverlet.runsettings
global.json		global.json
install.ps1		install.ps1
install.sh		install.sh

License

Aaronontheweb/freshdesk-cli

Folders and files

Latest commit

History

Repository files navigation

Freshdesk CLI

Features

Installation

Quick Install (Recommended)

From Source

Pre-built Binaries

Uninstallation

Configuration

Initial Setup

Environment Variables

Configuration File Location

Tab Completion

Installation

Activation

Features

Usage

Read-Only Mode

Ticket Operations

List Tickets

Get Ticket Details

Create Ticket

Update Ticket

Search Tickets

Reply to Tickets

Add Internal Notes

Export Operations

Attachment Operations

List Attachments

Download Attachment

Upload Attachment

Output Formats

Command Reference

Global Options

Config Commands

Ticket Commands

Attachment Commands

Examples

Daily Operations

Automation

Safe Exploration

Building from Source

Prerequisites

Build Commands

Supported Platforms

Architecture

Contributing

Development Guidelines

Pull Request Process

Troubleshooting

Common Issues

Performance

Security

Roadmap

License

Support

Acknowledgments

Author

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Contributors 2

Languages

Packages