5-Minute Quickstart

Follow this walkthrough to launch Lioran S3, configure the CLI, create a bucket, upload a file, inspect metadata, download the object, and interact using the TypeScript SDK.

---

Step 1: Start Lioran S3 Server

Start a local Lioran S3 server instance in development mode:

# From the repository root
cargo run --bin bastion-server

Or run via Docker:

docker run -d --name bastion -p 27118:27118 -v $(pwd)/data:/data liorans3/liorans3:pre-alpha

---

Step 2: Verify Server Health & Latency

Use the CLI ping command to verify the server is reachable:

liorans3 ping --endpoint http://127.0.0.1:27118

Expected Output

PONG: 3ms (status: ok, version: 0.1.0, endpoint: http://127.0.0.1:27118)

:::tip Common Failure: Connection Refused

• Cause: Server is not running or listening on a different port.
• Fix: Check BASTION_PORT environment variable or verify container status with docker ps. :::

---

Step 3: Configure the CLI

Initialize your local CLI profile using liorans3 configure:

liorans3 configure --endpoint http://127.0.0.1:27118 --username admin -P admin

Expected Output

Verifying connection to http://127.0.0.1:27118...
Connection verified: Server status 'ok', version '0.1.0'.
Profile 'default' configured and active.

:::info Bootstrap Password Notice In development mode, the default password is admin. In production mode (BASTION_ENV=production), you must specify the password configured in BASTION_ADMIN_PASSWORD and rotate it on first login. :::

---

Step 4: Create a Bucket

Create your first storage bucket named quickstart:

liorans3 bucket create quickstart --quota-gb 10

Expected Output

Bucket 'quickstart' created successfully (versioning: disabled, quota: 10.00 GiB).

Verify the bucket appears in the bucket list:

liorans3 bucket ls

Expected Output

NAME                     OWNER            QUOTA          VERSIONING   CREATED               
quickstart               admin            10.00 GiB      disabled     10/1/2026, 6:00:00 PM 

---

Step 5: Upload a File

Create a sample test file and upload it to the quickstart bucket:

echo "Hello from Lioran S3!" > hello.txt
liorans3 object put quickstart hello.txt ./hello.txt --content-type text/plain

Expected Output

Uploaded 'hello.txt' (22 B in 4ms, 0.01 MB/s, SHA-256: 8f4e2d...01a9)

---

Step 6: Inspect & List Objects

Query object metadata without downloading the body:

liorans3 object stat quickstart hello.txt

Expected Output

Object:         quickstart/hello.txt
Content-Type:   text/plain
Content-Length: 22 B (22 bytes)
SHA-256:        8f4e2d83b16954b52...
ETag:           "8f4e2d83b16954b52..."
Last-Modified:  2026-10-01T12:00:00.000Z
Accept-Ranges:  bytes

List all objects in the bucket:

liorans3 object ls quickstart

Expected Output

KEY                                  SIZE           TYPE                   MODIFIED              
hello.txt                            22 B           text/plain             10/1/2026, 6:00:00 PM 

---

Step 7: Download the Object

Download the stored object to a new local file:

liorans3 object get quickstart hello.txt ./downloaded-hello.txt

Expected Output

Downloaded 'hello.txt' to './downloaded-hello.txt' (22 B).

Or stream the bytes directly to standard output:

liorans3 object cat quickstart hello.txt

Output:

Hello from Lioran S3!

---

Step 8: Use the TypeScript Driver

Create a script app.ts in your Node.js project:

import { BastionClient } from "@liorans3/driver";
import * as fs from "node:fs";

async function main() {
  // 1. Initialize client
  const client = new BastionClient("bastion://admin:admin@127.0.0.1:27118");

  // 2. Select bucket
  const bucket = client.bucket("quickstart");

  // 3. Upload object
  await bucket.put("sdk-test.txt", "Stored via @liorans3/driver", {
    contentType: "text/plain",
  });
  console.log("Object uploaded via SDK");

  // 4. Download object
  const object = await bucket.get("sdk-test.txt");
  const content = await object.text();
  console.log("Retrieved content:", content);

  // 5. List objects in bucket
  const list = await bucket.list();
  console.log("Objects in bucket:", list.map((o) => o.key));
}

main().catch(console.error);

Run with tsx or node:

npx tsx app.ts

Output:

Object uploaded via SDK
Retrieved content: Stored via @liorans3/driver
Objects in bucket: [ 'hello.txt', 'sdk-test.txt' ]

---

Summary of Basic Commands

Action	CLI Command	SDK Equivalent
Check Health	liorans3 ping	await client.health()
Create Bucket	liorans3 bucket create <name>	await client.buckets.create(name)
List Buckets	liorans3 bucket ls	await client.buckets.list()
Upload Object	liorans3 object put <bucket> <key> <file>	await bucket.put(key, data)
Download Object	liorans3 object get <bucket> <key> <file>	await (await bucket.get(key)).writeToFile(path)
Delete Object	liorans3 object rm <bucket> <key>	await bucket.delete(key)