FessCTL

fessctl is a command-line interface (CLI) tool to manage Fess via its Admin API.

Fess is an open-source enterprise search server based on OpenSearch. fessctl allows developers and operators to automate and script administrative tasks such as:

• Creating or updating crawler configurations
• Managing users and roles
• Starting or stopping scheduled jobs
• Exporting and importing settings
• Monitoring system health

(Currently under development, more features and improvements are on the way. Stay tuned for updates!)

Installation and Usage

There are four ways to use fessctl:

Method 1: Install from PyPI (recommended)

fessctl is published to PyPI. Install it with pip, or use pipx / uv tool for an isolated, globally available CLI:

pip install fessctl
# or, for an isolated install:
pipx install fessctl
# or:
uv tool install fessctl

Usage

export FESS_ACCESS_TOKEN=your_access_token_here
export FESS_ENDPOINT=https://your-fess-server
export FESS_VERSION=15.7.0

fessctl --help
fessctl ping
fessctl user list

Method 2: Using Pre-built Docker Image

If you prefer a container-based workflow, use the pre-built Docker image:

docker run --rm \
  -e FESS_ENDPOINT=https://your-fess-server \
  -e FESS_ACCESS_TOKEN=your_access_token_here \
  -e FESS_VERSION=15.7.0 \
  ghcr.io/codelibs/fessctl:0.2.0 --help

Run actual commands:

docker run --rm \
  -e FESS_ENDPOINT=https://your-fess-server \
  -e FESS_ACCESS_TOKEN=your_access_token_here \
  -e FESS_VERSION=15.7.0 \
  ghcr.io/codelibs/fessctl:0.2.0 ping

docker run --rm \
  -e FESS_ENDPOINT=https://your-fess-server \
  -e FESS_ACCESS_TOKEN=your_access_token_here \
  -e FESS_VERSION=15.7.0 \
  ghcr.io/codelibs/fessctl:0.2.0 user list

Method 3: Building Your Own Docker Image

Clone the repository and build the Docker image locally:

git clone https://github.com/codelibs/fessctl.git
cd fessctl
docker build -t fessctl:latest .

Then run with your custom image:

docker run --rm \
  -e FESS_ENDPOINT=https://your-fess-server \
  -e FESS_ACCESS_TOKEN=your_access_token_here \
  -e FESS_VERSION=15.7.0 \
  fessctl:latest --help

Method 4: Install from Source

For development or when you need to modify the source code:

Requirements

• Python 3.13+
• uv (recommended for environment setup)

Setup

git clone https://github.com/codelibs/fessctl.git
cd fessctl
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv pip install -e src

Usage

export FESS_ACCESS_TOKEN=your_access_token_here
export FESS_ENDPOINT=https://your-fess-server
export FESS_VERSION=15.7.0

fessctl --help
fessctl ping
fessctl user list
fessctl webconfig create --name TestConfig --url https://test.config.com/

Environment Variables

All four methods require the following environment variables:

• FESS_ENDPOINT: The URL of your Fess server's API endpoint (default: http://localhost:8080)
• FESS_ACCESS_TOKEN: Bearer token for API authentication (required)
• FESS_VERSION: Target Fess version for API compatibility (default: 15.7.0). Set this to match your Fess server. Fess 14.x and 15.x are supported; the value controls version-specific behavior such as HTTP methods for CRUD operations and the health-check endpoint (/api/v1/health for versions before 15.7, /api/v2/health for 15.7 and later).

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Contributing

Pull requests are welcome! Feel free to open issues or discussions to suggest features, report bugs, or ask questions.