You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by ps...@apache.org on 2026/02/22 15:56:16 UTC

(opendal-oli) branch feat/apache-opendal-oli-skill created (now 1dbdbbd)

This is an automated email from the ASF dual-hosted git repository.

psiace pushed a change to branch feat/apache-opendal-oli-skill
in repository https://gitbox.apache.org/repos/asf/opendal-oli.git


      at 1dbdbbd  feat: add Apache OpenDAL Oli skill for direct data operations

This branch includes the following new commits:

     new 1dbdbbd  feat: add Apache OpenDAL Oli skill for direct data operations

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



(opendal-oli) 01/01: feat: add Apache OpenDAL Oli skill for direct data operations

Posted by ps...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

psiace pushed a commit to branch feat/apache-opendal-oli-skill
in repository https://gitbox.apache.org/repos/asf/opendal-oli.git

commit 1dbdbbd3ebe43377277f4bc99f38477e05f56f62
Author: Chojan Shang <ps...@apache.org>
AuthorDate: Sun Feb 22 15:56:00 2026 +0000

    feat: add Apache OpenDAL Oli skill for direct data operations
---
 skills/apache-opendal-oli/SKILL.md                 | 106 ++++++++++++++++++
 skills/apache-opendal-oli/agents/openai.yaml       |   4 +
 skills/apache-opendal-oli/references/commands.md   |  88 +++++++++++++++
 .../references/safety-troubleshooting.md           | 120 +++++++++++++++++++++
 4 files changed, 318 insertions(+)

diff --git a/skills/apache-opendal-oli/SKILL.md b/skills/apache-opendal-oli/SKILL.md
new file mode 100644
index 0000000..a5fd90c
--- /dev/null
+++ b/skills/apache-opendal-oli/SKILL.md
@@ -0,0 +1,106 @@
+---
+name: apache-opendal-oli
+description: Direct command playbooks for Apache OpenDAL Oli CLI data access and mutation. Use when Codex must run real `oli` commands to list, read, copy, move, delete, edit, stream, or benchmark data across local paths and `profile:/path` locations.
+---
+
+# Apache OpenDAL Oli
+
+## Command Principles
+
+- Prefer direct command execution over abstract planning.
+- Run read-only checks before mutating data.
+- Use explicit paths and explicit `--config` when environment consistency matters.
+
+## Direct Command Playbooks
+
+### Inspect Data Without Mutation
+
+```bash
+oli ls 's3:/warehouse/'
+oli ls -r 's3:/warehouse/2026/'
+oli ls -T 's3:/warehouse/'
+oli stat 's3:/warehouse/events.parquet'
+oli cat 's3:/warehouse/schema.json'
+```
+
+### Copy Local File To Remote
+
+```bash
+oli cp ./events.parquet 's3:/ingest/events.parquet'
+oli stat 's3:/ingest/events.parquet'
+```
+
+### Copy Remote File To Local
+
+```bash
+oli cp 's3:/ingest/events.parquet' ./events.parquet
+```
+
+### Copy Across Profiles
+
+```bash
+oli cp 's3:/warehouse/events.parquet' 'r2:/backup/events.parquet'
+oli stat 'r2:/backup/events.parquet'
+```
+
+### Recursive Directory Copy
+
+```bash
+oli ls -r 's3:/warehouse/2026/'
+oli cp -r 's3:/warehouse/2026/' 'r2:/backup/2026/'
+oli ls -r 'r2:/backup/2026/'
+```
+
+### Move File Or Directory
+
+```bash
+oli mv 's3:/staging/events.parquet' 's3:/warehouse/events.parquet'
+oli mv -r 's3:/staging/old-batch/' 's3:/archive/old-batch/'
+```
+
+### Safe Recursive Delete
+
+```bash
+oli ls -r 's3:/staging/to-delete/'
+oli rm -r 's3:/staging/to-delete/'
+oli ls 's3:/staging/'
+```
+
+### Stream Input To Object
+
+```bash
+printf '%s\n' '{"status":"ok"}' | oli tee 's3:/logs/healthcheck.json'
+```
+
+### Edit Remote File
+
+```bash
+EDITOR=vim oli edit 's3:/docs/README.md'
+```
+
+### Run Benchmark Suite
+
+```bash
+oli bench --config ./config.toml s3 ./suite.toml
+```
+
+## Hard Rules
+
+- Always use `profile:/path` syntax and avoid `://`.
+- Use `profile:/path` for remote targets and plain paths for local filesystem targets.
+- For directory-level mutations, explicitly use `-r` and inspect scope first.
+- For delete operations, list first, delete second, verify third.
+- For cross-profile copy and move, verify source and destination with `stat` or `ls`.
+- When non-default config is required, always pass `--config <path>` explicitly.
+
+## Failure Triage
+
+- `unknown profile`: check profile name and `config.toml`.
+- `missing 'type' in profile`: add profile `type`.
+- `Host part in a location is not supported`: replace `://` with `:/`.
+- Recursive command errors: confirm `-r` and target kind (file vs directory).
+
+## Resource Navigation
+
+- Read `references/commands.md` for command semantics and flags.
+- Read `references/safety-troubleshooting.md` for risk control and debugging.
diff --git a/skills/apache-opendal-oli/agents/openai.yaml b/skills/apache-opendal-oli/agents/openai.yaml
new file mode 100644
index 0000000..5e653a9
--- /dev/null
+++ b/skills/apache-opendal-oli/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Apache OpenDAL Oli"
+  short_description: "Direct command playbooks for Apache OpenDAL Oli CLI"
+  default_prompt: "Use $apache-opendal-oli to execute real Apache OpenDAL Oli CLI commands for data access and mutation."
diff --git a/skills/apache-opendal-oli/references/commands.md b/skills/apache-opendal-oli/references/commands.md
new file mode 100644
index 0000000..38acd47
--- /dev/null
+++ b/skills/apache-opendal-oli/references/commands.md
@@ -0,0 +1,88 @@
+# OLI Command Reference
+
+## Location Semantics
+
+- Use local filesystem mode when the argument does not contain `:/`.
+- Use remote profile mode when the argument is `<profile>:/<path>`.
+- Avoid `://` in location strings. `oli` treats host parts as invalid.
+
+Examples:
+
+```bash
+# local path
+oli ls './data/'
+
+# remote path
+oli ls 's3:/data/'
+
+# invalid syntax (do not use)
+oli ls 's3://data/'
+```
+
+## Config Resolution
+
+- Default config path:
+  - Linux: `~/.config/oli/config.toml`
+  - macOS: `~/Library/Application Support/oli/config.toml`
+  - Windows: `%APPDATA%\oli\config.toml`
+- Environment variables override file configuration.
+- Environment key format: `OLI_PROFILE_<PROFILE>_<OPTION>`
+
+Examples:
+
+```bash
+OLI_PROFILE_S3_TYPE=s3
+OLI_PROFILE_S3_BUCKET=my-bucket
+OLI_PROFILE_S3_REGION=us-east-1
+```
+
+## Global Parameter
+
+`--config <path>` is available through `ConfigParams` in command implementations.
+
+```bash
+oli --config ./config.toml ls 's3:/'
+oli cp --config ./config.toml './a.txt' 's3:/a.txt'
+```
+
+## Commands
+
+### Read-Only
+
+- `oli ls <target>`
+- `oli ls -r <target>`
+- `oli ls -T <target>`
+- `oli cat <target>`
+- `oli stat <target>`
+- `oli config view`
+
+### Mutating
+
+- `oli cp <source> <destination>`
+- `oli cp -r <source_dir> <destination_dir>`
+- `oli cp --content-type application/json <source> <destination>`
+- `oli mv <source> <destination>`
+- `oli mv -r <source_dir> <destination_dir>`
+- `oli rm <target>`
+- `oli rm -r <target_dir>`
+- `oli tee <destination>`
+- `oli tee -a <destination>`
+- `oli edit <target>`
+
+### Benchmark
+
+- `oli bench <profile> <suite.toml>`
+
+## Binary Aliases
+
+`oli` supports executable-name aliases:
+
+- `obench` -> `bench`
+- `ocat` -> `cat`
+- `ocp` -> `cp`
+- `ols` -> `ls`
+- `orm` -> `rm`
+- `ostat` -> `stat`
+- `omv` -> `mv`
+
+Prefer `oli <subcommand>` for clarity unless alias behavior is explicitly required.
diff --git a/skills/apache-opendal-oli/references/safety-troubleshooting.md b/skills/apache-opendal-oli/references/safety-troubleshooting.md
new file mode 100644
index 0000000..7a9b20b
--- /dev/null
+++ b/skills/apache-opendal-oli/references/safety-troubleshooting.md
@@ -0,0 +1,120 @@
+# OLI Safety And Troubleshooting
+
+## Safe Execution Checklist
+
+1. Resolve intent:
+- `read-only` for inspection
+- `mutating` for data changes
+
+2. Validate source and destination paths with read-only checks:
+
+```bash
+oli ls 's3:/path/'
+oli stat 's3:/path/to/object'
+```
+
+3. Execute mutation only after verification:
+
+```bash
+oli cp 's3:/path/to/object' 'r2:/backup/object'
+```
+
+4. Verify result:
+
+```bash
+oli stat 'r2:/backup/object'
+```
+
+## High-Risk Operations
+
+### Recursive Delete
+
+- Always inspect scope before `rm -r`.
+
+```bash
+oli ls -r 's3:/staging/prefix/'
+oli rm -r 's3:/staging/prefix/'
+oli ls 's3:/staging/'
+```
+
+### Recursive Move
+
+- `mv -r` moves data and deletes source entries afterward.
+- Validate source and destination roots before running.
+
+### Recursive Copy
+
+- Use `cp -r` only for directory-level workflows.
+- Confirm destination is a directory or a new path intended as directory root.
+
+## Common Errors And Fixes
+
+### `unknown profile: <name>`
+
+Cause:
+- Profile name missing in config and environment.
+
+Fix:
+- Add `[profiles.<name>]` in `config.toml`, or set `OLI_PROFILE_<NAME>_TYPE`.
+- Use `oli config view` to inspect available profiles.
+
+### `missing 'type' in profile`
+
+Cause:
+- Profile exists but has no `type` key.
+
+Fix:
+- Add `type = "<service>"` in the profile table.
+
+### `Host part in a location is not supported`
+
+Cause:
+- Used `://` instead of `:/`.
+
+Fix:
+- Replace `s3://a/b` with `s3:/a/b`.
+
+### `can not move a directory in non-recursive mode`
+
+Cause:
+- Tried to move directory with `mv` without `-r`.
+
+Fix:
+- Use `mv -r`.
+
+### `Recursive copy destination '...' exists but is not a directory`
+
+Cause:
+- `cp -r` destination points to an existing file.
+
+Fix:
+- Use a directory destination path.
+
+### `No configuration profiles found in ...`
+
+Cause:
+- Config file missing or empty at the selected `--config` path.
+
+Fix:
+- Create config file with at least one profile.
+
+## Operational Patterns
+
+### Cross-Profile Transfer
+
+```bash
+oli cp 's3:/dataset/part-0001.parquet' 'r2:/archive/part-0001.parquet'
+oli stat 'r2:/archive/part-0001.parquet'
+```
+
+### Controlled Metadata Check
+
+```bash
+oli stat 's3:/dataset/part-0001.parquet'
+```
+
+Use the output to validate:
+- `size`
+- `etag` (if available)
+- `content-type`
+- `last-modified`