EasyTask CLI Documentation¶

Welcome to the EasyTask CLI Documentation! The EasyTask CLI is a powerful command-line tool that lets you manage tasks, groups, events, agents, and the scheduler directly from your terminal. Use it to automate workflows, script bulk operations, and integrate EasyTask into your CI/CD pipelines.

🖥️ EasyTask CLI Overview¶

easytask -h

 Usage: easytask [OPTIONS] COMMAND [ARGS]...

 EasyTask CLI — manage tasks, groups, events, agents, and scheduler.

╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                               │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────╮
│ health      Check if easytask is reachable.                                 │
│ auth        Authentication commands.                                        │
│ tasks       Task management.                                                │
│ groups      Group management.                                               │
│ events      Event and action commands.                                      │
│ scheduler   Scheduler operations.                                           │
│ agents      Agent management.                                               │
│ admin       Admin — user and role management.                               │
╰─────────────────────────────────────────────────────────────────────────────╯

🖥️ Command Groups¶

Health¶

Health Check — Check if EasyTask is reachable.

Authentication¶

Commands for logging in, logging out, and managing your session.

Login — Login to EasyTask and store credentials.
Logout — Logout and clear stored credentials.
Who Am I — Show current user profile.
Refresh Token — Refresh the authentication token.
Switch Instance — Switch to a different instance.

Tasks¶

Manage tasks — list, create, update, delete, export, and import.

List Tasks — List tasks.
Get Task — Get task details.
Create Task — Create a task from inline parameters or a JSON file.
Update Task — Update a task from inline parameters or a JSON file.
Delete Task — Delete a task.
Export Tasks — Export all tasks and groups as JSON.
Import Tasks — Import tasks and groups from a JSON file.

Groups¶

Manage task groups — list, create, update, and delete.

List Groups — List groups.
Get Group — Get group details.
Create Group — Create a group from inline parameters or a JSON file.
Update Group — Update a group from inline parameters or a JSON file.
Delete Group — Delete a group.

Events¶

Event and action commands — force run, enable/disable, freeze/unfreeze, refresh, and more.

List Events — List events.
Get Event — Get event details.
Ack Event — Poll for event ACK status.
Force Run — Force execute a task.
Enable Task — Enable a task on the scheduler.
Disable Task — Disable a task on the scheduler.
Freeze Task — Freeze a task.
Unfreeze Task — Unfreeze a task.
Terminate Task — Terminate a running task.
Modify Status — Modify a task's status.
Refresh Task — Reload task definition on scheduler.
Refresh Group — Reload group definition on scheduler.
Refresh Graph — Refresh the dependency graph on scheduler.
Refresh Calendar — Refresh holiday calendars on scheduler.
Adhoc Command — Execute an adhoc command on worker queues.

Scheduler¶

Scheduler operations — health, task runs, logs, upcoming tasks, and more.

Health — Check scheduler health.
Task Runs — List task runs with lifecycle.
Task Run Logs — Get logs for a task run.
Upcoming Tasks — Show upcoming scheduled tasks.
Task Statuses — Show latest status per task.
State Codes — List task state codes.
Logs — List scheduler run logs.

Agents¶

Agent management — list, get details, restart, and monitor workers and queues.

List Agents — List all agents.
Get Agent — Get agent details.
Restart Agent — Send restart action to an agent.
Task Stats — Get Celery task stats for an agent.
Workers — List active Celery workers.
Queues — Show worker-to-queue mapping.

Admin¶

Admin — user and role management.

List Users — List all users.
Get User — Get user details.
Create User — Create a new user from a JSON file.
Update User — Update a user from a JSON file.
Delete User — Delete a user.
Reset Password — Reset a user's password.
User Roles — Get a user's roles.
Set Roles — Add or remove roles for a user.
Roles List — List available EasyTask roles.

❓ Frequently Asked Questions¶

How do I install the EasyTask CLI?¶

The EasyTask CLI is installed as part of the EasyTask agent setup. Follow the installation guide to download and install the CLI on your system. After installation, verify with easytask health.

Do I need to authenticate before using the CLI?¶

Yes. Run easytask auth login to authenticate and store your credentials locally. Once logged in, all subsequent commands use your stored session. You can check your current session with easytask auth whoami.

Can I use the CLI in CI/CD pipelines?¶

Absolutely. The CLI supports non-interactive login via --username and --password flags, making it ideal for automated environments. You can also set the EASYTASK_API_URL environment variable to configure the API endpoint without passing --api-url each time.

What output formats does the CLI support?¶

Most list and get commands support --output table|json|yaml (default: table). Use JSON or YAML output for scripting and automation, for example: easytask tasks list --output json.

How do I manage multiple EasyTask instances?¶

Use easytask auth switch-instance to switch between registered instances. You can also specify --api-url on any command to target a different instance temporarily.

Can I import and export tasks in bulk?¶

Yes. Use easytask tasks export to export all tasks and groups as JSON, and easytask tasks import to import them. This is useful for migrating task definitions between environments or backing up your configuration.

What roles and permissions does the CLI enforce?¶

The CLI enforces the same role-based access control as the EasyTask web interface. Admin commands (under easytask admin) require the admin role or higher. Non-superadmin users cannot assign the superadmin role. Use easytask admin roles-list to view available roles.

⏭️ Next Steps¶

Health Check — Verify your CLI connection to EasyTask.
Login — Authenticate and start using the CLI.
List Tasks — Browse your existing tasks.
Force Run — Trigger a task execution immediately.
List Agents — Monitor your registered agents.
Task Definition — Learn about task structure and configuration.
Complete User Guide — Full walkthrough of EasyTask features.