Skip to content

tutorial.md

Latest commit

 

History

History
204 lines (133 loc) · 8.74 KB

tutorial.md

File metadata and controls

204 lines (133 loc) · 8.74 KB
Raw

xyCLI Tutorial

Let's build a small piece of automation from your terminal. You'll explore the dashboard, create a shell Event, watch a job run, and add a Web Hook that fires when the job succeeds. Then you'll update your script and export the finished automation.

For installation and connection settings, start with Getting started. The command reference has the full options for every command used here.

Before you begin

This walkthrough assumes:

  • xyCLI is installed and connected to your xyOps instance.
  • You have an online Linux or macOS worker with a POSIX shell, the built-in Shell Plugin (shellplug), and an enabled Category.
  • Your API Key can create and edit Events, run jobs, and use the selected Category and Group. For the Web Hook steps, it also needs create_web_hooks and edit_web_hooks.
  • You have an HTTP endpoint that accepts JSON POST requests and lets you inspect incoming requests. This could be your own application or a request-capture endpoint. The xyOps conductor must be able to reach it.

Use the IDs printed by xyCLI as you go. Replace placeholders such as EVENT_ID and HOOK_ID with those actual IDs, and replace the example Hook URL with your endpoint.

1. Explore the dashboard

Run xy to see your system at a glance:

xy

The dashboard brings together server health, active Alerts and jobs, queued work, and rate limits. Check the upcoming schedule to see what xyOps expects to run soon:

xy upcoming

Now browse the workers and resources available for your first Event:

xy servers
xy groups
xy categories
xy plugins --type event

Choose a Group with an online, enabled worker, and note its ID. Also note an enabled Category ID and confirm that the Shell Plugin is available. You can inspect a worker or Group more closely with xy server SERVER_ID or xy group GROUP_ID.

2. Create your first Event

An Event is a reusable definition of what to run and where to run it. Each execution of that Event becomes a separate job.

Make a local file named hello.sh containing:

#!/bin/sh
echo "Hello from xyCLI!"
echo "Running on $(hostname)"
sleep 3
echo "All done."

Create an enabled Event with a manual trigger. Replace CATEGORY_ID and GROUP_ID with the IDs you selected:

xy event create --title "Hello from xyCLI" \
	--enabled true --category CATEGORY_ID \
	--plugin shellplug --targets '["GROUP_ID"]' \
	--params.script @./hello.sh \
	--triggers '[{"type":"manual","enabled":true}]'

The @./hello.sh value reads your local script into the Event. The Group determines which workers are eligible to run it, and the manual trigger allows you to launch it on demand. There is no schedule, so this Event runs when you ask it to.

The creation command prints the new Event ID. Use it to review the saved definition:

xy event EVENT_ID

3. Run a job and follow its output

Launch the Event and follow the job until it finishes:

xy run EVENT_ID --follow

You should see the greeting, the worker's hostname, and the final message. xyCLI then displays the completed job report.

Each run gets its own Job ID. Use the ID printed at launch to revisit its report or read its output log:

xy job JOB_ID
xy job log JOB_ID

Find all of today's completed runs of your Event:

xy jobs --event EVENT_ID --date today

You can also launch without --follow and open the Job ID afterward. xy job JOB_ID follows an active job or displays a completed report, depending on its state.

4. Create a custom Web Hook

Let's send a JSON notification to your HTTP endpoint. A Web Hook stores the destination and request settings; an Event action will decide when to fire it.

Create a local file named notification-body.txt containing this request template:

{
	"source": "xycli-tutorial",
	"message": {{ stringify(text) }}
}

text is the notification message generated by xyOps. stringify(text) turns it into a quoted JSON string, including escaping quotes and line breaks. Leave that expression unquoted in the template: xyOps fills it in before sending the request, producing valid JSON.

Create the Hook, replacing https://hooks.example.com/xycli with your endpoint:

xy hook create --title "xyCLI Success Notification" \
	--url https://hooks.example.com/xycli \
	--method POST --body @./notification-body.txt

xyCLI prints the new Hook ID. The default headers include Content-Type: application/json, and new Hooks are enabled. Creating the Hook saves its definition without sending a request.

Inspect it, then send a test request:

xy hook HOOK_ID
xy hook test HOOK_ID

The test makes a real HTTP request from xyOps and displays the request, response, and timing details. Your endpoint should receive a JSON object with source set to xycli-tutorial and a test notification in message. The test uses sample notification data; it does not run your Event.

If the request fails, check the URL, the endpoint's response, and network access from the conductor. If your destination needs authentication or a different payload, adjust the Hook to match its API before continuing.

5. Fire the Hook when your Event succeeds

Attach an enabled Web Hook action to the Event. Replace HOOK_ID inside the JSON with the Hook ID from the previous step:

xy event update EVENT_ID \
	--action '{"type":"web_hook","enabled":true,"condition":"success","web_hook":"HOOK_ID","text":"Hello from xyCLI finished successfully."}'

The success condition fires when the job completes successfully. The web_hook field selects the saved Hook, and text adds your custom message to the notification. A failed run will not fire this success action.

The singular --action option appends to the Event's existing actions. Run this update once; repeating it adds another action entry. Review the Event to confirm the new action is present:

xy event EVENT_ID

Now run the Event again:

xy run EVENT_ID --follow

After the job succeeds, check your endpoint for the notification. The same Hook template now receives the real job's notification text, including your custom message. Your Event and Hook are saved, so future successful runs use the same action automatically.

The completed job report includes the actions that fired and their results. If the notification does not arrive, revisit xy job JOB_ID and inspect the Web Hook action result as well as your endpoint's request log.

6. Update your script from your editor

Add another message to your local hello.sh, then upload the revised script:

xy event update EVENT_ID --params.script @./hello.sh
xy run EVENT_ID --follow

The update changes the saved script while preserving the Event's other settings, including the success action. Editing your local file alone does not update xyOps; the update command sends the new contents.

This is a simple way to iterate on automation with your usual editor. For a larger collection of Events and Plugins, explore the filesystem sync overview.

7. Export the Event and its Hook together

Save your finished Event as an xyOps Portable Data Format (XYPDF) file, including the Web Hook referenced by its action:

xy event EVENT_ID --export ./hello-event.json --deps web_hooks

The export includes the Event's saved script, manual trigger, and success action, plus the custom Hook definition. You can review the file, keep it in Git, or import it into another instance using xyCLI or the xyOps web interface.

This example selects only the Hook dependency. Importing elsewhere also requires compatible Plugins, Categories, and target Groups; use --deps all to include all supported portable dependencies. Individual workers are not portable.

For more ideas, return to Explore and manage xyOps or browse the screenshot gallery.