# fessctl

**Repository Path**: mirrors_codelibs/fessctl

## Basic Information

- **Project Name**: fessctl
- **Description**: CLI tool to manage Fess using the admin API
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-25
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FessCTL

[![PyPI version](https://img.shields.io/pypi/v/fessctl.svg)](https://pypi.org/project/fessctl/)
[![Python versions](https://img.shields.io/pypi/pyversions/fessctl.svg)](https://pypi.org/project/fessctl/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/codelibs/fessctl/blob/main/LICENSE)

**fessctl** is a command-line interface (CLI) tool to manage [Fess](https://fess.codelibs.org/) 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](https://pypi.org/project/fessctl/). Install it with `pip`,
or use [`pipx`](https://pipx.pypa.io/) / [`uv tool`](https://docs.astral.sh/uv/guides/tools/)
for an isolated, globally available CLI:

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

#### Usage
```bash
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:

```bash
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:

```bash
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:

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

Then run with your custom image:

```bash
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`](https://github.com/astral-sh/uv) (recommended for environment setup)

#### Setup
```bash
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
```bash
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](https://github.com/codelibs/fessctl/blob/main/LICENSE) file for details.

## Contributing

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