@fnndsc/chili 3.2.5

package/docs/02_context.adoc

@@ -0,0 +1,128 @@
+= context
+
+== intro
+
+An important idea in `chili` is the concept of _context_. The _context_ of a command can be thought of as the scope of its activity -- or alternatively the possible set of implicit data which the command can access as it performs its actions.
+
+== context operates at two levels
+
+To truly understand context, it helps to see it operating on two distinct levels. One determines *where* you are connecting, and the other determines *what* you are doing inside that connection.
+
+=== level 1: the environment (global context)
+
+This is the highest level. It defines the "universe" you are operating in.
+
+|===
+| Pillar | Concept | Description
+
+| **The CUBE**
+| Server
+| The physical ChRIS server address (URL). You might have a "Production" CUBE and a "Local Testing" CUBE. Switching this context completely changes the universe of available data.
+
+| **The User**
+| Identity
+| Who you are on that server. You might be `admin` on Local and `jane` on Production. `chili` remembers your login token for each identity independently.
+|===
+
+=== level 2: the resource (local session)
+
+Once you are inside an environment (User + CUBE), you need a way to navigate. This level acts like your "working directory" or "focus."
+
+|===
+| Pillar | Concept | Description
+
+| **The Folder**
+| Filesystem
+| Your current path in the ChRIS storage (e.g., `/home/jane/data`). Commands like `ls` look here.
+
+| **The Feed**
+| Workflow
+| A specific analysis execution (Feed ID). Commands related to logs or status check this feed.
+
+| **The Plugin**
+| Tool
+| A specific plugin instance or definition. Commands listing parameters or instances use this scope.
+|===
+
+Imagine a standard shell. Level 1 is like choosing which computer to SSH into. Level 2 is what you do (`cd`, `ls`) once you are logged in. `chili` handles both layers seamlessly.
+
+== viewing your context
+
+At any time, you can ask `chili` "where am I?" by simply typing:
+
+```bash
+chili context get
+```
+
+This will show you your current active URL, your username, and any specific "working directories" you have set.
+
+If you want to see the bigger picture -- all the users and servers `chili` knows about -- you can ask for the full view:
+
+```bash
+chili context get --full
+```
+
+== changing your context
+
+Moving around is easy and can be done at either level.
+
+=== switching resources (level 2)
+
+Let's say you want to switch your focus to a specific directory in your ChRIS storage so you can explore files there. You can "cd" into it like this:
+
+```bash
+chili context set --ChRISfolder /home/jane.doe/data
+```
+
+Now, any file operations you perform will happen in `/home/jane.doe/data` automatically.
+
+=== switching environments (level 1)
+
+You can also switch your identity or server completely. If you have previously logged in as user `bob` on a different server, you can switch back to him with a single command, and `chili` will remember exactly where `bob` left off (his Level 2 context):
+
+```bash
+chili context set --ChRISuser bob
+```
+
+== scoped execution (inline context)
+
+Sometimes you don't want to change your "global" settings just to run one command. You want to peek into a directory or run a plugin in a specific feed without "cd-ing" there permanently.
+
+`chili` allows you to define a **temporary scope** right in the command itself. It looks almost like a simplified URL or query string.
+
+=== the syntax
+
+You can prepend any command with `key=value` arguments. `chili` interprets these as a temporary context override for *just that command*.
+
+```bash
+chili scope=<value> [scope=<value>...] <command>
+```
+
+=== examples
+
+**Peeking into a folder (Level 2 override):**
+Instead of changing your directory, just tell `chili` to look at `/home/rudolph` for this one command:
+
+```bash
+chili folder=/home/rudolph files list
+```
+
+**Acting on a specific feed (Level 2 override):**
+Run a note listing on feed ID 105, regardless of your current context:
+
+```bash
+chili feed=105 note list
+```
+
+**The Full URI Power (Level 1 & 2 override):**
+You can even specify the user and server inline! This allows you to run a command on a completely different server as a different user without logging out:
+
+```bash
+chili "rudolph@https://cube.chrisproject.org?folder=/home/rudolph" files list
+```
+
+In this example, `chili` temporarily connects to the remote CUBE as user `rudolph`, sets the working directory to `/home/rudolph`, lists the files, and then immediately returns you to your previous local session. It is incredibly powerful for scripting or cross-server management.
+
+== persistence
+
+The best part about context is that it is persistent. You can close your terminal, reboot your computer, or go on vacation. When you come back and open `chili` again, you will be exactly where you were. This makes managing long-running workflows or jumping between complex tasks much less of a headache.

package/docs/03_searchable.adoc

@@ -0,0 +1,134 @@
+= searchable
+
+== intro
+
+In `chili`, you often need to tell a command _what_ to operate on. "Run _this_ plugin." "Delete _that_ feed." "List files in _this_ directory."
+
+Usually, computer programs want cryptic ID numbers for this. "Run plugin #42." But humans are bad at remembering numbers. We prefer names. `chili` understands this and provides a powerful feature we call _searchables_.
+
+A _searchable_ is just a text string you give to a command. `chili` looks at that string and figures out what you mean.
+
+== simple search
+
+Most of the time, you just want to find something by its name. Let's say you want to run the `pl-dircopy` plugin. You don't need to look up its ID number. You just tell `chili`:
+
+```bash
+chili plugin run pl-dircopy
+```
+
+`chili` sees "pl-dircopy", realizes it's a name, finds the plugin for you, and runs it. Simple.
+
+== explicit search
+
+Sometimes, "just the name" isn't enough. Maybe there are five different versions of `pl-dircopy` and you need a specific one. Or maybe you are looking for a feed created by a specific person.
+
+In these cases, you can use a special key-value syntax. It looks like `key: value`.
+
+For example, to find a plugin with a specific version:
+
+```bash
+chili plugin run "name: pl-dircopy, version: 2.1.1"
+```
+
+Notice how we separated the two facts we know (the name and the version) with a comma. `chili` will find the single plugin that matches _both_ of these rules.
+
+You can use any filter that the ChRIS API supports. If you want to find a feed created by user `bob`:
+
+```bash
+chili feed delete "owner_username: bob"
+```
+
+NOTE: If your searchable matches multiple items, `chili` will warn you but continue using the first match. To avoid ambiguity, be as specific as possible (e.g., use `name_exact` instead of `name`, or add version constraints).
+
+== batch operations
+
+Some commands (like `delete`) support operating on multiple resources at once. Use the `++` separator to combine multiple searchables:
+
+```bash
+chili plugins delete "id:77++id:33++name:pl-test"
+```
+
+This will delete all three plugins in sequence. Each searchable is resolved independently, and if you don't use `--force`, you'll get a confirmation prompt for each one.
+
+This is useful for cleaning up multiple test resources or deleting several related items at once.
+
+== using searchables in context
+
+This gets really powerful when combined with context. Imagine you want to start a session working on a specific plugin, but you don't know its ID. You can set your context using a searchable!
+
+```bash
+chili context set --ChRISplugin "name: pl-dircopy"
+```
+
+Now `chili` finds the plugin, gets its ID, and locks your session to it. Any subsequent commands that ask "which plugin?" will automatically use `pl-dircopy`.
+
+This flexibility means you almost never have to memorize an ID number again. Just describe what you want, and let `chili` find it.
+
+== advanced: the Searchable class
+
+_For developers and advanced users:_
+
+Starting with cumin v0.4.1, searchables are implemented as a formal TypeScript class. While `chili` automatically handles string-based searchables, you can use the `Searchable` class directly for type safety and validation:
+
+```typescript
+import { Searchable } from '@fnndsc/cumin';
+
+// Create searchables explicitly
+const simple = Searchable.simple("pl-dircopy");
+const compound = Searchable.compound("name:pl-dircopy,version:1.3.2");
+const batch = Searchable.batch("id:77++id:33");
+
+// Auto-detect type
+const auto = Searchable.from("name:pl-dircopy");
+
+// Check type
+if (auto.isCompound()) {
+  console.log("This is a compound searchable");
+}
+
+// Get query parameters
+const params = compound.toQueryParams();
+// { name: "pl-dircopy", version: "1.3.2" }
+
+// Split batch into parts
+const parts = batch.toBatchSearchables();
+// [Searchable(id:77), Searchable(id:33)]
+
+// Validate format
+if (simple.validate()) {
+  console.log("Valid searchable!");
+}
+```
+
+All ChRIS operations accept both strings and `Searchable` objects, so you can use whichever is more convenient for your use case.
+
+== examples cheat sheet
+
+Here are some common ways to use searchables:
+
+|===
+| Goal | Searchable String
+
+| **Find by Name**
+| `"pl-dircopy"`
+
+| **Find by ID**
+| `"id: 14"`
+
+| **Exact Name Match**
+| `"name_exact: pl-dircopy"`
+
+| **Specific Version**
+| `"name: pl-dircopy, version: 2.0"`
+
+| **Recent Feeds**
+| `"limit: 5"` (implicitly sorts by default)
+
+| **Feed by Creator**
+| `"owner_username: bob"`
+
+| **Delete Multiple Items**
+| `"id:77++id:33++name:pl-test"`
+|===
+
+_-30-_

package/docs/10_everyday_examples.adoc

@@ -0,0 +1,9 @@
+= intro
+
+== welcome
+
+Welome to the inline `chili` documentation system! This set of documents provides help text for each `chili` command. Additionally several important concepts like _searchable_ and _context_ are discussed.
+
+== how to use
+
+To use this documentation system, simply read it!

package/docs/11_upload_data.adoc

@@ -0,0 +1,146 @@
+= uploading data to ChRIS
+
+== intro
+
+The `path upload` command provides a powerful way to upload entire directory trees from your local filesystem to ChRIS. Unlike single-file uploads with `file create --from-file`, `path upload` recursively scans directories and preserves their structure in the ChRIS filesystem.
+
+== basic usage
+
+To upload a local directory to ChRIS:
+
+```bash
+chili folder=/home/user/uploads path upload ~/Downloads/dataset
+```
+
+This command:
+1. Validates that `/home/user/uploads` exists in ChRIS (fails if it doesn't)
+2. Uploads the `dataset` directory and all its contents
+3. Creates `/home/user/uploads/dataset/` in ChRIS with the full directory tree preserved
+
+== how it works
+
+=== folder validation
+
+The `folder=` context parameter specifies the *parent directory* in ChRIS where your upload will be placed. This directory **must already exist** in ChRIS—the command will fail if it doesn't.
+
+```bash
+# This works if /home/jane.doe/data exists in ChRIS
+chili folder=/home/jane.doe/data path upload ./experiment_results
+
+# This fails if /home/jane.doe/nonexistent does not exist
+chili folder=/home/jane.doe/nonexistent path upload ./experiment_results
+```
+
+=== directory structure preservation
+
+The basename of the source directory is preserved in the target path. For example:
+
+```bash
+chili folder=/home/user/uploads path upload ~/Downloads/experiment1
+```
+
+Creates the following structure in ChRIS:
+```
+/home/user/uploads/experiment1/
+  ├── data.csv
+  ├── notes.txt
+  └── results/
+      └── output.json
+```
+
+The `experiment1` directory itself becomes part of the ChRIS filesystem path.
+
+=== recursive upload
+
+All subdirectories and files are uploaded recursively:
+
+```bash
+# Local structure:
+~/project/
+  ├── src/
+  │   ├── main.py
+  │   └── utils.py
+  └── data/
+      └── input.csv
+
+# After: chili folder=/home/user/work path upload ~/project
+# ChRIS structure:
+/home/user/work/project/
+  ├── src/
+  │   ├── main.py
+  │   └── utils.py
+  └── data/
+      └── input.csv
+```
+
+== progress tracking
+
+During upload, `chili` displays a progress bar showing:
+- Current file count and total files
+- Percentage completion
+- Estimated time remaining
+- Data transferred
+
+```
+Transferring [████████░░] 45% | ETA: 12s | 23/50 files | 1.2 MB/2.8 MB
+```
+
+== common patterns
+
+=== uploading experiment data
+
+```bash
+# Upload today's experiment results
+chili folder=/home/researcher/experiments/2025-11-29 path upload ~/lab_data/run_42
+```
+
+=== organizing by project
+
+```bash
+# Create project directory first
+chili chefs mkdir /home/user/projects/projectX
+
+# Upload data into it
+chili folder=/home/user/projects/projectX path upload ~/local_work/dataset
+```
+
+=== multiple uploads to same parent
+
+```bash
+# Upload multiple datasets to the same parent directory
+chili folder=/home/user/raw_data path upload ~/data/batch1
+chili folder=/home/user/raw_data path upload ~/data/batch2
+chili folder=/home/user/raw_data path upload ~/data/batch3
+```
+
+Results in:
+```
+/home/user/raw_data/
+  ├── batch1/
+  ├── batch2/
+  └── batch3/
+```
+
+== error handling
+
+The command will fail with a clear error if:
+
+1. **Target folder doesn't exist:**
+   ```
+   Folder context '/home/user/nonexistent' does not exist in CUBE.
+   Please specify an existing directory.
+   ```
+
+2. **Source path doesn't exist:**
+   ```
+   Error: Source path '~/Downloads/missing' not found
+   ```
+
+3. **Permission issues:**
+   ChRIS will reject the upload if you don't have write permissions to the target folder.
+
+== see also
+
+- `chefs ls` - List directory contents to verify uploads
+- `chefs mkdir` - Create target directories before uploading
+- `file create --from-file` - Upload single files

package/docs/12_create_a_feed.adoc

@@ -0,0 +1,9 @@
+= intro
+
+== welcome
+
+Welome to the inline `chili` documentation system! This set of documents provides help text for each `chili` command. Additionally several important concepts like _searchable_ and _context_ are discussed.
+
+== how to use
+
+To use this documentation system, simply read it!