diff --git a/docs/reference/rc/README.md b/docs/reference/rc/README.md new file mode 100644 index 0000000..402aa1d --- /dev/null +++ b/docs/reference/rc/README.md @@ -0,0 +1,67 @@ +# rc Command Reference + +This reference documents the operations exposed by `rc`, the RustFS S3-compatible command-line client. The structure follows the command-reference style used by MinIO `mc`: each operation describes its purpose, syntax, parameters, examples, and behavior, while keeping the examples specific to `rc`. + +`rc` supports both noun-first command groups and legacy command names. Prefer the noun-first groups for new scripts: + +| Operation | Preferred form | Legacy-compatible form | +| --- | --- | --- | +| Configure targets | [`rc alias`](alias.md) | none | +| Bucket workflows | [`rc bucket`](bucket.md) | `rc ls`, `rc mb`, `rc rb`, `rc event`, `rc cors`, `rc version`, `rc anonymous`, `rc quota`, `rc ilm`, `rc replicate` | +| Object workflows | [`rc object`](object.md) | `rc ls`, `rc cp`, `rc mv`, `rc rm`, `rc cat`, `rc head`, `rc stat`, `rc find`, `rc tree`, `rc share` | +| Administrative workflows | [`rc admin`](admin.md) | none | +| Streaming upload | [`rc pipe`](pipe.md) | none | +| Difference reports | [`rc diff`](diff.md) | none | +| Mirroring | [`rc mirror`](mirror.md) | none | +| S3 Select | [`rc sql`](sql.md) | none | +| Tags | [`rc tag`](tag.md) | none | +| Shell completions | [`rc completions`](completions.md) | none | + +Legacy command pages remain documented for users migrating from MinIO `mc`-style workflows: + +- [`rc ls`](ls.md) +- [`rc mb`](mb.md) +- [`rc rb`](rb.md) +- [`rc cat`](cat.md) +- [`rc head`](head.md) +- [`rc stat`](stat.md) +- [`rc cp`](cp.md) +- [`rc mv`](mv.md) +- [`rc rm`](rm.md) +- [`rc find`](find.md) +- [`rc event`](event.md) +- [`rc cors`](cors.md) +- [`rc tree`](tree.md) +- [`rc share`](share.md) +- [`rc version`](version.md) +- [`rc anonymous`](anonymous.md) +- [`rc quota`](quota.md) +- [`rc ilm`](ilm.md) +- [`rc replicate`](replicate.md) + +## Path Format + +Remote paths use `ALIAS/BUCKET/KEY` form. An alias-only path such as `local/` refers to a configured S3-compatible service. A bucket path such as `local/photos` refers to a bucket. An object path such as `local/photos/2026/image.jpg` refers to a specific object key. + +## Output Modes + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | + +## Credentials + +Credentials are stored through aliases. Configure an alias before running remote operations: + +```bash +rc alias set local http://localhost:9000 ACCESS_KEY SECRET_KEY +``` + +Do not put production credentials in examples, logs, issue descriptions, or screenshots. diff --git a/docs/reference/rc/admin.md b/docs/reference/rc/admin.md new file mode 100644 index 0000000..59e3fab --- /dev/null +++ b/docs/reference/rc/admin.md @@ -0,0 +1,78 @@ +# rc admin + +## Purpose + +The `rc admin` operation manages RustFS or MinIO-compatible administrative APIs, including cluster information, healing, pools, expansion, decommissioning, rebalance workflows, IAM users, policies, groups, and service accounts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] admin +rc admin info [OPTIONS] +rc admin heal [OPTIONS] +rc admin pool [POOL] [OPTIONS] +rc admin expand +rc admin decommission [OPTIONS] +rc admin rebalance +rc admin user ... +rc admin policy ... +rc admin group ... +rc admin service-account ... +``` + +## Commands + +| Command | Description | +| --- | --- | +| `info` | Display cluster, server, or disk information. | +| `heal` | Start, stop, or inspect healing operations. | +| `pool` | List pools and inspect pool status. | +| `expand` | Manage post-expansion data rebalancing. Alias: `scale`. | +| `decommission` | Manage server pool decommissioning. Alias: `decom`. | +| `rebalance` | Manage post-expansion rebalancing. | +| `user` | Manage IAM users. | +| `policy` | Manage IAM policies and attachments. | +| `group` | Manage IAM groups and group membership. | +| `service-account` | Manage service accounts. | + +## Examples + +Show cluster information: + +```bash +rc admin info cluster local +``` + +Start a deep heal for a prefix: + +```bash +rc admin heal start local --bucket logs --prefix 2026/ --scan-mode deep +``` + +Create a user and attach a policy: + +```bash +rc admin user add local analyst STRONG_PASSWORD +rc admin policy attach local readonly --user analyst +``` + +Create a service account with a policy file: + +```bash +rc admin service-account create local SA_ACCESS_KEY SA_SECRET_KEY --policy ./policy.json +``` + +## Behavior + +Admin operations use the configured alias to create an admin client. The credentials behind the alias must have permissions for the requested administrative API. The command accepts aliases with or without a trailing slash. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/alias.md b/docs/reference/rc/alias.md new file mode 100644 index 0000000..b3ccd7c --- /dev/null +++ b/docs/reference/rc/alias.md @@ -0,0 +1,77 @@ +# rc alias + +## Purpose + +The `rc alias` operation manages named S3-compatible service endpoints in the local `rc` configuration. Use aliases to avoid repeating endpoint URLs and credentials in every command. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] alias +rc [GLOBAL OPTIONS] alias set [OPTIONS] +rc [GLOBAL OPTIONS] alias list [-l|--long] +rc [GLOBAL OPTIONS] alias remove +``` + +## Commands + +| Command | Description | +| --- | --- | +| `set` | Add a new alias or replace an existing alias. | +| `list` | List configured aliases. | +| `remove` | Remove an alias from local configuration. | + +## Parameters + +| Parameter | Description | +| --- | --- | +| `NAME` | Local alias name, such as `local`, `s3`, or `rustfs`. | +| `ENDPOINT` | S3-compatible endpoint URL, such as `http://localhost:9000`. | +| `ACCESS_KEY` | Access key ID for the endpoint. | +| `SECRET_KEY` | Secret access key for the endpoint. | +| `--region` | AWS region to associate with the alias. Defaults to `us-east-1`. | +| `--signature` | Signature version, `v4` or `v2`. Defaults to `v4`. | +| `--bucket-lookup` | Bucket lookup style: `auto`, `path`, or `dns`. Defaults to `auto`. | +| `--insecure` | Allow insecure TLS connections for this alias. | +| `-l, --long` | Show full alias details when listing aliases. | + +## Examples + +Configure a local RustFS or MinIO-compatible service: + +```bash +rc alias set local http://localhost:9000 ACCESS_KEY SECRET_KEY +``` + +Configure AWS S3 with an explicit region: + +```bash +rc alias set s3 https://s3.amazonaws.com ACCESS_KEY SECRET_KEY --region us-east-1 +``` + +List aliases with endpoint details: + +```bash +rc alias list --long +``` + +Remove an alias: + +```bash +rc alias remove old-local +``` + +## Behavior + +`alias set` overwrites an existing alias with the same name. `alias list` does not print secret keys. Commands that need a remote service resolve the alias name before creating an S3 or admin client. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/anonymous.md b/docs/reference/rc/anonymous.md new file mode 100644 index 0000000..aee0b33 --- /dev/null +++ b/docs/reference/rc/anonymous.md @@ -0,0 +1,50 @@ +# rc anonymous + +## Purpose + +`rc anonymous` manages anonymous bucket or prefix access. It is a legacy-compatible command; prefer `rc bucket anonymous` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] anonymous +rc anonymous set +rc anonymous set-json +rc anonymous get +rc anonymous get-json +rc anonymous list +rc anonymous links [-r|--recursive] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `PATH` | Bucket or prefix path, `ALIAS/BUCKET[/PREFIX]`. | +| `PERMISSION` | One of `private`, `public`, `download`, or `upload`. | +| `FILE` | Policy JSON file for `set-json`. | +| `-r, --recursive` | Recursively list public links. | + +## Examples + +```bash +rc bucket anonymous set download local/public/reports +rc anonymous get local/public/reports +rc anonymous links local/public/reports --recursive +rc anonymous set private local/public +``` + +## Behavior + +Setting prefix-level anonymous access replaces the bucket policy document with statements generated for the target prefix. Setting `private` is bucket-level because it clears the anonymous policy. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/bucket.md b/docs/reference/rc/bucket.md new file mode 100644 index 0000000..07e5228 --- /dev/null +++ b/docs/reference/rc/bucket.md @@ -0,0 +1,97 @@ +# rc bucket + +## Purpose + +The `rc bucket` operation is the preferred noun-first entry point for bucket-oriented workflows. It groups bucket listing, creation, deletion, notification, CORS, versioning, quota, anonymous access, lifecycle, and replication operations under one command family. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] bucket +rc bucket list [OPTIONS] +rc bucket create [OPTIONS] +rc bucket remove [OPTIONS] +rc bucket event ... +rc bucket cors ... +rc bucket version ... +rc bucket quota ... +rc bucket anonymous ... +rc bucket lifecycle ... +rc bucket replication ... +``` + +## Commands + +| Command | Description | +| --- | --- | +| `list` | List buckets for an alias or list objects under a bucket path. | +| `create` | Create a bucket. | +| `remove` | Remove a bucket. | +| `event` | Manage bucket notification rules. | +| `cors` | Manage bucket CORS rules. | +| `version` | Manage bucket versioning and object versions. | +| `quota` | Manage bucket quota. | +| `anonymous` | Manage anonymous bucket or prefix access. | +| `lifecycle` | Manage lifecycle rules, remote tiers, and object restore requests. | +| `replication` | Manage bucket replication rules and replication status. | + +## Parameters + +| Parameter | Description | +| --- | --- | +| `PATH` | `ALIAS/`, `ALIAS/BUCKET`, or `ALIAS/BUCKET/PREFIX`. | +| `--recursive` | Recursively list objects for `bucket list`. | +| `--versions` | Include object versions when listing supported versioned buckets. | +| `--summarize` | Show totals only for list output. | +| `--ignore-existing` | Do not fail if the bucket already exists when creating it. | +| `--with-versioning` | Enable versioning when creating the bucket. | +| `--with-lock` | Enable object lock when creating the bucket. | +| `--force` | Force destructive or capability-gated operations where supported. | +| `--dangerous` | Remove a bucket even when incomplete multipart uploads exist. | + +## Examples + +List buckets for an alias: + +```bash +rc bucket list local/ +``` + +Create a versioned bucket with object lock: + +```bash +rc bucket create local/archive --with-versioning --with-lock +``` + +List notification rules: + +```bash +rc bucket event list local/archive +``` + +Set CORS from an XML or JSON file: + +```bash +rc bucket cors set local/archive cors.xml +``` + +Check replication status: + +```bash +rc bucket replication status local/archive +``` + +## Behavior + +Prefer `rc bucket ...` for new scripts. Legacy commands such as `rc mb`, `rc rb`, `rc event`, `rc cors`, `rc version`, `rc anonymous`, `rc quota`, `rc ilm`, and `rc replicate` remain available and delegate to the same implementations. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/cat.md b/docs/reference/rc/cat.md new file mode 100644 index 0000000..d840ec2 --- /dev/null +++ b/docs/reference/rc/cat.md @@ -0,0 +1,43 @@ +# rc cat + +## Purpose + +`rc cat` prints the full contents of an object to stdout. It is a legacy-compatible command; prefer `rc object show` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] cat [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET/KEY` | Object path to read. | +| `--enc-key` | Encrypt or decrypt with the given base64-encoded key. | +| `--rewind` | Read object state at a specific time where supported. | +| `--version-id` | Read a specific object version. | + +## Examples + +```bash +rc cat local/reports/summary.txt +rc object show local/reports/summary.txt --version-id VERSION_ID +rc cat local/reports/summary.txt --rewind 2026-05-01T00:00:00Z +``` + +## Behavior + +Object bytes are written to stdout, so redirect output when reading binary objects. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/completions.md b/docs/reference/rc/completions.md new file mode 100644 index 0000000..2fbe608 --- /dev/null +++ b/docs/reference/rc/completions.md @@ -0,0 +1,46 @@ +# rc completions + +## Purpose + +`rc completions` generates shell completion scripts for supported shells. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] completions +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `SHELL` | One of `bash`, `elvish`, `fish`, `powershell`, or `zsh`. | + +## Examples + +Generate zsh completions: + +```bash +rc completions zsh > _rc +``` + +Generate bash completions: + +```bash +rc completions bash > rc.bash +``` + +## Behavior + +The command writes the completion script to stdout. Install the generated file according to the conventions of your shell and operating system. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/cors.md b/docs/reference/rc/cors.md new file mode 100644 index 0000000..90cced3 --- /dev/null +++ b/docs/reference/rc/cors.md @@ -0,0 +1,48 @@ +# rc cors + +## Purpose + +`rc cors` manages bucket CORS configuration. It is a legacy-compatible command; prefer `rc bucket cors` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] cors +rc cors list +rc cors get +rc cors set [OPTIONS] [SOURCE] +rc cors remove +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET` | Bucket whose CORS rules are managed. | +| `SOURCE` | JSON or XML CORS file. Use `-` to read from stdin. | +| `--file` | Legacy flag for the CORS file; mutually exclusive with positional `SOURCE`. | +| `--force` | Force operation even if capability detection fails. | + +## Examples + +```bash +rc bucket cors list local/web +rc bucket cors set local/web cors.xml +cat cors.json | rc cors set local/web - +rc cors remove local/web +``` + +## Behavior + +`list` and `get` read the current CORS rules. `set` replaces the bucket CORS configuration with the supplied JSON or XML document. `remove` clears the CORS configuration. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/cp.md b/docs/reference/rc/cp.md new file mode 100644 index 0000000..9c1e586 --- /dev/null +++ b/docs/reference/rc/cp.md @@ -0,0 +1,59 @@ +# rc cp + +## Purpose + +`rc cp` copies files and objects between local paths and S3-compatible remote paths. It is a legacy-compatible command; prefer `rc object copy` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] cp [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `SOURCE` | Local file, local directory, or remote object/prefix path. This version accepts one source and one target. | +| `TARGET` | Local or remote destination path. | +| `-r, --recursive` | Recursively copy a directory or prefix. | +| `--overwrite` | Overwrite destination data where supported. | +| `--dry-run` | Show planned copies without copying data. | +| `--preserve` | Preserve applicable metadata. | +| `--content-type` | Set object content type for uploads. | +| `--storage-class` | Set destination storage class for uploads where supported. | + +## Examples + +Upload a file: + +```bash +rc cp ./report.json local/reports/report.json +``` + +Upload a directory recursively: + +```bash +rc object copy ./reports/ local/reports/ --recursive +``` + +Copy between buckets on the same alias: + +```bash +rc cp local/reports/summary.json local/archive/summary.json +``` + +## Behavior + +The last path is the target. Sources can mix local and remote paths only where the command can infer a valid copy direction. S3-to-S3 copies are limited to paths under the same alias in the current implementation; use `rc mirror` for remote-to-remote synchronization across aliases. Use trailing slashes consistently when copying directory-like prefixes. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/diff.md b/docs/reference/rc/diff.md new file mode 100644 index 0000000..7c8b6bd --- /dev/null +++ b/docs/reference/rc/diff.md @@ -0,0 +1,42 @@ +# rc diff + +## Purpose + +`rc diff` compares two locations and reports objects that are missing, different, or identical depending on selected options. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] diff [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `SOURCE` | Local or remote source path. | +| `TARGET` | Local or remote target path. | +| `-r, --recursive` | Compare recursively. | +| `--diff-only` | Show only differences instead of all compared entries. | + +## Examples + +```bash +rc diff local/reports backup/reports --recursive +rc diff ./reports local/reports --recursive --json +``` + +## Behavior + +Diff is read-only. Use it before copy, mirror, or remove workflows to inspect drift between two locations. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/event.md b/docs/reference/rc/event.md new file mode 100644 index 0000000..0077a0e --- /dev/null +++ b/docs/reference/rc/event.md @@ -0,0 +1,46 @@ +# rc event + +## Purpose + +`rc event` manages bucket notification rules. It is a legacy-compatible command; prefer `rc bucket event` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] event +rc event add [OPTIONS] +rc event list [OPTIONS] +rc event remove [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET` | Bucket whose notification configuration is managed. | +| `ARN` | Notification target ARN. | +| `--event EVENT` | Event filter. Can be supplied more than once. | +| `--force` | Force operation even if capability detection fails. | + +## Examples + +```bash +rc bucket event add local/reports arn:aws:sns:us-east-1:123456789012:topic --event s3:ObjectCreated:* +rc event list local/reports +rc bucket event remove local/reports arn:aws:sns:us-east-1:123456789012:topic +``` + +## Behavior + +Adding a rule configures notifications for the specified ARN. Removing a rule targets the matching ARN. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/find.md b/docs/reference/rc/find.md new file mode 100644 index 0000000..288229f --- /dev/null +++ b/docs/reference/rc/find.md @@ -0,0 +1,48 @@ +# rc find + +## Purpose + +`rc find` searches objects under a bucket path using name, path, size, time, and metadata filters. It is a legacy-compatible command; prefer `rc object find` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] find [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `PATH` | Bucket or prefix to search. | +| `--name` | Match object name with a glob-like pattern. | +| `--older` | Match objects older than a duration such as `7d`. | +| `--newer` | Match objects newer than a duration such as `1h`. | +| `--larger` | Match objects larger than a size such as `10M`. | +| `--smaller` | Match objects smaller than a size such as `500K`. | +| `--maxdepth` | Limit search depth; `0` means unlimited. | +| `--count` | Print only the number of matches. | +| `--exec` | Execute a command for each match, using `{}` as the placeholder. | +| `--print` | Print full paths instead of paths relative to the search root. | + +## Examples + +```bash +rc find local/reports --name '*.json' +rc object find local/logs --newer 1d --larger 10M +``` + +## Behavior + +Find evaluates filters against objects returned by the backend. Duration and size suffixes are parsed by `rc`, so use explicit units for scripts. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/head.md b/docs/reference/rc/head.md new file mode 100644 index 0000000..c7b5357 --- /dev/null +++ b/docs/reference/rc/head.md @@ -0,0 +1,42 @@ +# rc head + +## Purpose + +`rc head` prints the beginning of an object. It is a legacy-compatible command; prefer `rc object head` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] head [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET/KEY` | Object path to preview. | +| `-n, --lines` | Number of lines to print. Defaults to `10`. | +| `-c, --bytes` | Number of bytes to print. | +| `--version-id` | Read a specific object version. | + +## Examples + +```bash +rc head local/logs/app.log --lines 20 +rc object head local/data/archive.bin --bytes 512 +``` + +## Behavior + +Use `--bytes` for binary files or fixed-size previews. Use `--lines` for text objects. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/ilm.md b/docs/reference/rc/ilm.md new file mode 100644 index 0000000..e90ba8f --- /dev/null +++ b/docs/reference/rc/ilm.md @@ -0,0 +1,75 @@ +# rc ilm + +## Purpose + +`rc ilm` manages bucket lifecycle configuration, remote storage tiers, and restore requests for transitioned objects. It is a legacy-compatible command; prefer `rc bucket lifecycle` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] ilm +rc ilm rule ... +rc ilm tier ... +rc ilm restore [OPTIONS] +``` + +## Rule Operations + +| Command | Description | +| --- | --- | +| `rule add` | Add an expiration or transition rule. | +| `rule edit` | Edit an existing lifecycle rule. | +| `rule list` | List lifecycle rules on a bucket. | +| `rule remove` | Remove one rule by ID or all rules. | +| `rule export` | Export lifecycle configuration as JSON. | +| `rule import` | Import lifecycle configuration from JSON. | + +## Tier Operations + +| Command | Description | +| --- | --- | +| `tier add` | Add a remote storage tier. | +| `tier edit` | Edit tier credentials. | +| `tier list` | List configured tiers. | +| `tier info` | Show tier statistics. | +| `tier remove` | Remove a tier. | + +## Common Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET` | Bucket whose lifecycle configuration is managed. | +| `--id` | Lifecycle rule identifier. | +| `--prefix` | Restrict a rule to a key prefix. | +| `--tags` | Restrict a rule to tag filters. | +| `--expiry-days` | Expire current objects after the specified number of days. | +| `--transition-days` | Transition objects after the specified number of days. | +| `--storage-class` | Remote tier or storage class for transition rules. | +| `--all` | Remove all lifecycle rules where supported. | +| `--days` | Number of days to keep a restored copy. Defaults to `1`. | +| `--force` | Force operation even if capability detection fails. | + +## Examples + +```bash +rc bucket lifecycle rule add local/reports --expiry-days 30 --prefix logs/ +rc ilm rule list local/reports +rc ilm rule export local/reports > lifecycle.json +rc ilm tier add rustfs WARM local --endpoint http://remote:9000 --access-key ACCESS_KEY --secret-key SECRET_KEY --bucket warm +rc ilm restore local/reports/archive/object.dat --days 7 +``` + +## Behavior + +Lifecycle behavior is applied by the storage service. Rule support, tier support, and restore support depend on backend capabilities. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/ls.md b/docs/reference/rc/ls.md new file mode 100644 index 0000000..bb52a78 --- /dev/null +++ b/docs/reference/rc/ls.md @@ -0,0 +1,44 @@ +# rc ls + +## Purpose + +`rc ls` lists buckets or objects. It is a legacy-compatible command; prefer `rc bucket list` for bucket workflows and `rc object list` for object workflows. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] ls [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `PATH` | `ALIAS/` to list buckets, or `ALIAS/BUCKET[/PREFIX]` to list objects. | +| `-r, --recursive` | Recursively list objects. | +| `--versions` | Show object versions where supported. | +| `--incomplete` | Include incomplete multipart uploads. | +| `--summarize` | Show totals only. | + +## Examples + +```bash +rc ls local/ +rc ls local/reports --recursive +rc bucket list local/reports --versions +``` + +## Behavior + +When `PATH` contains only an alias, `rc ls` lists buckets. When it contains a bucket, it lists objects under the optional prefix. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/mb.md b/docs/reference/rc/mb.md new file mode 100644 index 0000000..59870bd --- /dev/null +++ b/docs/reference/rc/mb.md @@ -0,0 +1,44 @@ +# rc mb + +## Purpose + +`rc mb` creates a bucket. It is a legacy-compatible command; prefer `rc bucket create` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] mb [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET` | Target bucket path to create. | +| `-p, --ignore-existing` | Treat an existing bucket as success. | +| `--region` | Override the alias default region for bucket creation. | +| `--with-lock` | Enable object locking on the new bucket. | +| `--with-versioning` | Enable bucket versioning after creation. | + +## Examples + +```bash +rc mb local/reports +rc bucket create local/archive --with-versioning --with-lock +rc mb local/reports --ignore-existing +``` + +## Behavior + +Bucket creation uses the endpoint and credentials from the alias. Object locking must be enabled when the bucket is created. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/mirror.md b/docs/reference/rc/mirror.md new file mode 100644 index 0000000..edd27a1 --- /dev/null +++ b/docs/reference/rc/mirror.md @@ -0,0 +1,45 @@ +# rc mirror + +## Purpose + +`rc mirror` synchronizes objects from one remote S3-compatible location to another remote S3-compatible location. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] mirror [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `SOURCE` | Remote source bucket or prefix path, in `ALIAS/BUCKET[/PREFIX]` form. | +| `TARGET` | Remote destination bucket or prefix path, in `ALIAS/BUCKET[/PREFIX]` form. | +| `--overwrite` | Overwrite changed destination objects. | +| `--remove` | Delete target objects that no longer exist in the source. | +| `-n, --dry-run` | Show planned changes without applying them. | +| `-P, --parallel` | Number of parallel transfer workers. Defaults to `4`. | + +## Examples + +```bash +rc mirror local/source backup/source --parallel 8 +rc mirror local/web/site backup/web/site --dry-run +rc mirror local/web/site backup/web/site --overwrite --remove +``` + +## Behavior + +Mirror is intended for remote prefix-level synchronization. Local filesystem paths are not supported by the current implementation. Use `--dry-run` first when combining `--overwrite` and `--remove`. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/mv.md b/docs/reference/rc/mv.md new file mode 100644 index 0000000..abfcb64 --- /dev/null +++ b/docs/reference/rc/mv.md @@ -0,0 +1,42 @@ +# rc mv + +## Purpose + +`rc mv` moves files or objects between local and S3-compatible locations. It is a legacy-compatible command; prefer `rc object move` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] mv [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `SOURCE` | Local path or remote object/prefix path to move. | +| `TARGET` | Local or remote destination path. | +| `-r, --recursive` | Move a directory or prefix recursively. | +| `--dry-run` | Show planned changes without moving data. | + +## Examples + +```bash +rc mv local/inbox/report.json local/archive/report.json +rc object move ./incoming/ local/inbox/ --recursive +``` + +## Behavior + +Move operations copy data to the target and remove the source after a successful copy. Review recursive moves with `--dry-run` before running destructive operations. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/object.md b/docs/reference/rc/object.md new file mode 100644 index 0000000..7e88227 --- /dev/null +++ b/docs/reference/rc/object.md @@ -0,0 +1,90 @@ +# rc object + +## Purpose + +The `rc object` operation is the preferred noun-first entry point for object workflows. It groups listing, copy, move, remove, metadata, preview, search, tree, and presigned URL operations. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] object +rc object list [OPTIONS] +rc object copy [OPTIONS] +rc object move [OPTIONS] +rc object remove [OPTIONS] ... +rc object stat [OPTIONS] +rc object show [OPTIONS] +rc object head [OPTIONS] +rc object find [OPTIONS] +rc object tree [OPTIONS] +rc object share [OPTIONS] +``` + +## Commands + +| Command | Description | +| --- | --- | +| `list` | List objects under a bucket path. | +| `copy` | Copy local files to S3, S3 objects to local paths, or S3 objects between remote paths. | +| `move` | Move objects or files by copying then deleting the source. | +| `remove` | Remove one or more objects. | +| `stat` | Show object metadata. | +| `show` | Print the full object body. | +| `head` | Print the first lines or bytes of an object. | +| `find` | Search object keys with filters. | +| `tree` | Display object keys as a tree. | +| `share` | Generate a presigned object URL. | + +## Common Parameters + +| Parameter | Description | +| --- | --- | +| `SOURCE` | Local path or remote `ALIAS/BUCKET/KEY`. Copy accepts one source and one target in this version. | +| `TARGET` | Local destination or remote `ALIAS/BUCKET[/PREFIX]`. | +| `PATH` | Remote object or prefix path. | +| `--recursive` | Recurse into directories or prefixes for copy, list, remove, or tree operations. | +| `--dry-run` | Print planned changes without mutating data where supported. | +| `--versions` | Include versions where the backend supports object versioning. | +| `--content-type` | Set content type for upload or streaming commands. | + +## Examples + +Upload a file: + +```bash +rc object copy ./report.json local/reports/report.json +``` + +Download an object: + +```bash +rc object copy local/reports/report.json ./report.json +``` + +Remove a prefix after previewing it: + +```bash +rc object remove local/reports/tmp/ --recursive --dry-run +rc object remove local/reports/tmp/ --recursive --force +``` + +Generate a one-day download URL: + +```bash +rc object share local/reports/report.json --expire 1d +``` + +## Behavior + +Prefer `rc object ...` for new scripts. Legacy commands such as `rc cp`, `rc mv`, `rc rm`, `rc cat`, `rc head`, `rc stat`, `rc find`, `rc tree`, and `rc share` remain available for compatibility. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/pipe.md b/docs/reference/rc/pipe.md new file mode 100644 index 0000000..b16cda0 --- /dev/null +++ b/docs/reference/rc/pipe.md @@ -0,0 +1,41 @@ +# rc pipe + +## Purpose + +`rc pipe` streams stdin directly into an object. Use it for generated data, shell pipelines, and backups that should not be written to a temporary local file first. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] pipe [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET/KEY` | Destination object path. | +| `--content-type` | Object content type. Defaults to `application/octet-stream`. | +| `--storage-class` | Storage class for the uploaded object. | + +## Examples + +```bash +tar -czf - ./logs | rc pipe local/backups/logs.tar.gz --content-type application/gzip +printf 'hello\n' | rc pipe local/tmp/hello.txt --content-type text/plain +``` + +## Behavior + +The command reads from stdin until EOF and uploads that stream as the destination object. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/quota.md b/docs/reference/rc/quota.md new file mode 100644 index 0000000..65f8159 --- /dev/null +++ b/docs/reference/rc/quota.md @@ -0,0 +1,44 @@ +# rc quota + +## Purpose + +`rc quota` manages bucket quota. It is a legacy-compatible command; prefer `rc bucket quota` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] quota +rc quota set +rc quota info +rc quota clear +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET` | Bucket whose quota is managed. | +| `SIZE` | Quota value in bytes or units such as `10G`, `500M`, or `10KB`. | + +## Examples + +```bash +rc bucket quota set local/reports 100G +rc quota info local/reports +rc bucket quota clear local/reports +``` + +## Behavior + +Quota commands require backend support for bucket quota APIs. Clearing quota removes the configured bucket quota. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/rb.md b/docs/reference/rc/rb.md new file mode 100644 index 0000000..442c872 --- /dev/null +++ b/docs/reference/rc/rb.md @@ -0,0 +1,41 @@ +# rc rb + +## Purpose + +`rc rb` removes a bucket. It is a legacy-compatible command; prefer `rc bucket remove` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] rb [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET` | Bucket path to remove. | +| `--force` | Delete objects before removing a non-empty bucket. | +| `--dangerous` | Remove the bucket even when incomplete multipart uploads exist. | + +## Examples + +```bash +rc rb local/empty-bucket +rc bucket remove local/old-bucket --force +``` + +## Behavior + +Without `--force`, the backend must allow deletion of the bucket as-is. Use destructive options carefully; they can delete object data before removing the bucket. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/replicate.md b/docs/reference/rc/replicate.md new file mode 100644 index 0000000..e12e7ee --- /dev/null +++ b/docs/reference/rc/replicate.md @@ -0,0 +1,61 @@ +# rc replicate + +## Purpose + +`rc replicate` manages bucket replication configuration and status. It is a legacy-compatible command; prefer `rc bucket replication` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] replicate +rc replicate add [OPTIONS] --remote-bucket +rc replicate update [OPTIONS] --id +rc replicate list [OPTIONS] +rc replicate status [OPTIONS] +rc replicate remove [OPTIONS] +rc replicate export [OPTIONS] +rc replicate import [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `SOURCE_ALIAS/BUCKET` | Source bucket for replication. | +| `--remote-bucket TARGET_ALIAS/BUCKET` | Destination bucket for a new rule. | +| `--id` | Rule identifier to update or remove. | +| `--replicate` | Comma-separated flags: `delete`, `delete-marker`, `existing-objects`. | +| `--priority` | Rule priority. Defaults to `1` for new rules. | +| `--storage-class` | Destination storage class override. | +| `--bandwidth` | Bandwidth limit in bytes per second; `0` means unlimited. | +| `--sync` | Enable synchronous replication. | +| `--prefix` | Key prefix filter. | +| `--healthcheck-seconds` | Health check interval. Defaults to `60` for new rules. | +| `--disable-proxy` | Disable replication proxy. | +| `--all` | Remove all rules. | +| `--force` | Force operation even if capability detection fails. | + +## Examples + +```bash +rc bucket version enable local/reports +rc bucket version enable backup/reports +rc bucket replication add local/reports --remote-bucket backup/reports --replicate delete,existing-objects +rc replicate status local/reports +rc replicate export local/reports > replication.json +``` + +## Behavior + +Replication generally requires versioning on source and destination buckets. The target bucket is resolved through its own alias, so configure both source and destination aliases before adding rules. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/rm.md b/docs/reference/rc/rm.md new file mode 100644 index 0000000..13f0bf8 --- /dev/null +++ b/docs/reference/rc/rm.md @@ -0,0 +1,46 @@ +# rc rm + +## Purpose + +`rc rm` removes objects. It is a legacy-compatible command; prefer `rc object remove` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] rm [OPTIONS] ... +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `PATH` | One or more remote object or prefix paths. | +| `-r, --recursive` | Remove objects recursively under a prefix. | +| `-f, --force` | Run without interactive confirmation where required. | +| `--dry-run` | Show objects that would be removed. | +| `--versions` | Remove object versions where supported. | +| `--purge` | Remove all versions and delete markers under the target where supported. | +| `--bypass` | Bypass governance retention if the backend and credentials allow it. | + +## Examples + +```bash +rc rm local/reports/tmp.json +rc object remove local/reports/tmp/ --recursive --dry-run +rc object remove local/reports/tmp/ --recursive --force +``` + +## Behavior + +Recursive and version-aware deletions can remove many objects. Use `--dry-run` to inspect the target set before running destructive commands. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/share.md b/docs/reference/rc/share.md new file mode 100644 index 0000000..b8ce3b5 --- /dev/null +++ b/docs/reference/rc/share.md @@ -0,0 +1,42 @@ +# rc share + +## Purpose + +`rc share` generates presigned URLs for object sharing. It is a legacy-compatible command; prefer `rc object share` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] share [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET/KEY` | Object to share. | +| `-e, --expire` | URL expiration duration. Defaults to `7d`. | +| `--upload` | Generate an upload URL where supported. | +| `--content-type` | Content type for upload-style URLs. | + +## Examples + +```bash +rc share local/reports/summary.pdf --expire 24h +rc object share local/uploads/inbox.bin --upload --expire 1h +``` + +## Behavior + +Presigned URLs inherit the permissions and endpoint behavior of the alias credentials. Treat generated URLs as temporary credentials until they expire. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/sql.md b/docs/reference/rc/sql.md new file mode 100644 index 0000000..a3bc7ce --- /dev/null +++ b/docs/reference/rc/sql.md @@ -0,0 +1,43 @@ +# rc sql + +## Purpose + +`rc sql` runs an S3 Select SQL expression against an object and streams query results to stdout. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] sql [OPTIONS] --query +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET/KEY` | Object to query. | +| `--query` | SQL expression to run. | +| `--input-format` | Input format: `csv`, `json`, or `parquet` where supported. Defaults to `csv`. | +| `--output-format` | Output format: `csv` or `json`. Defaults to `csv`. | +| `--compression` | Compression type: `none`, `gzip`, or `bzip2`. Defaults to `none`. | + +## Examples + +```bash +rc sql local/data/report.csv --query 'SELECT s._1 FROM S3Object s' +rc sql local/data/events.jsonl --query 'SELECT * FROM S3Object' --input-format json --output-format json --compression gzip +``` + +## Behavior + +The backend must support S3 Select for the target object format. Query results are written to stdout, so redirect output when storing results. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/stat.md b/docs/reference/rc/stat.md new file mode 100644 index 0000000..7cd6a78 --- /dev/null +++ b/docs/reference/rc/stat.md @@ -0,0 +1,41 @@ +# rc stat + +## Purpose + +`rc stat` shows object metadata. It is a legacy-compatible command; prefer `rc object stat` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] stat [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET/KEY` | Object path to inspect. | +| `--version-id` | Inspect a specific object version. | +| `--rewind` | Inspect object state at a specific time where supported. | + +## Examples + +```bash +rc stat local/reports/summary.json +rc object stat local/reports/summary.json --json +``` + +## Behavior + +Metadata output includes object identity and storage metadata such as size, modified time, ETag, content type, and user metadata when available. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/tag.md b/docs/reference/rc/tag.md new file mode 100644 index 0000000..4c9ee58 --- /dev/null +++ b/docs/reference/rc/tag.md @@ -0,0 +1,46 @@ +# rc tag + +## Purpose + +`rc tag` manages bucket and object tags. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] tag +rc tag list [OPTIONS] +rc tag set [OPTIONS] --tags KEY=VALUE [--tags KEY=VALUE ...] +rc tag remove [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `PATH` | Bucket path or object path whose tags are managed. | +| `-t, --tags KEY=VALUE` | Tag key-value pair to set. May be repeated. | +| `--version-id` | Target a specific object version where supported. | +| `--force` | Force operation even if capability detection fails. | + +## Examples + +```bash +rc tag set local/reports/summary.json --tags env=prod --tags owner=analytics +rc tag list local/reports/summary.json +rc tag remove local/reports/summary.json +``` + +## Behavior + +Tag operations use S3-compatible tagging APIs. Object-version targeting depends on backend support. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/tree.md b/docs/reference/rc/tree.md new file mode 100644 index 0000000..348a201 --- /dev/null +++ b/docs/reference/rc/tree.md @@ -0,0 +1,44 @@ +# rc tree + +## Purpose + +`rc tree` displays object keys in a tree-like view. It is a legacy-compatible command; prefer `rc object tree` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] tree [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `PATH` | Bucket or prefix to display. | +| `-L, --level` | Maximum tree depth. Defaults to `3`. | +| `-d, --dirs-only` | Show only directory-like prefixes. | +| `-f, --full-path` | Show full path prefixes. | +| `-P, --pattern` | Include only keys matching a pattern. | +| `-s, --size` | Show object sizes. | + +## Examples + +```bash +rc tree local/reports -L 2 +rc object tree local/reports --recursive --size +``` + +## Behavior + +Tree output is optimized for human inspection of key organization. Use `rc object list --json` for machine-readable inventory. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. | diff --git a/docs/reference/rc/version.md b/docs/reference/rc/version.md new file mode 100644 index 0000000..3321551 --- /dev/null +++ b/docs/reference/rc/version.md @@ -0,0 +1,48 @@ +# rc version + +## Purpose + +`rc version` manages bucket versioning and lists object versions. It is a legacy-compatible command; prefer `rc bucket version` for new scripts. + +## Syntax + +```bash +rc [GLOBAL OPTIONS] version +rc version enable +rc version suspend +rc version info +rc version list [OPTIONS] +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `ALIAS/BUCKET` | Bucket whose versioning state is managed. | +| `ALIAS/BUCKET[/PREFIX]` | Bucket or prefix whose versions are listed. | +| `-n, --max` | Maximum number of versions to list. Defaults to `100`. | +| `--force` | Force operation even if capability detection fails. | + +## Examples + +```bash +rc bucket version enable local/reports +rc version info local/reports +rc bucket version list local/reports --max 200 +rc version suspend local/reports +``` + +## Behavior + +Versioning changes apply at the bucket level. Listing versions requires backend support for S3 versioning APIs. + +Global options shown in command syntax use the same meaning everywhere: + +| Option | Description | +| --- | --- | +| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. | +| `--json` | Emit JSON output where the command supports structured output. | +| `--no-color` | Disable terminal colors. | +| `--no-progress` | Disable progress bars. | +| `-q, --quiet` | Suppress non-error output. | +| `--debug` | Enable debug logging. |