Metadata-Version: 2.4
Name: fessctl
Version: 0.2.0
Summary: CLI tool to manage Fess using the admin API
Author-email: "CodeLibs, Inc." <info@codelibs.co>
License-Expression: Apache-2.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx==0.28.1
Requires-Dist: pyyaml==6.0.2
Requires-Dist: typer[all]==0.16.0
Provides-Extra: dev
Requires-Dist: pytest>=7.1.0; extra == "dev"
Requires-Dist: testcontainers>=3.9.0; extra == "dev"
Requires-Dist: requests>=2.28.0; extra == "dev"
Dynamic: license-file

# FessCTL [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](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: Using Pre-built Docker Image

The easiest way to get started is using 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.1.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.1.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.1.0 user list
```

### Method 2: Building Your Own Docker Image

Clone the repository and build the Docker image locally:

```bash
git clone https://github.com/your-org/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 3: Install from Source with pip

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/your-org/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/
```

### Method 4: Install from PyPI

`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.6.1

fessctl --help
fessctl ping
fessctl user list
```

## 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.
