# Using with Ocean CLI

### Setup

Make sure the following environment variables are exported before running any storage commands:

```bash
export PRIVATE_KEY=<your-private-key>
export RPC=<rpc-url>          # e.g. https://base.drpc.org
export NODE_URL=<node-url>    # e.g. https://test1.oncompute.ai
```

Ensure the CLI is built: `npm run build`.

***

#### Access List Commands

Persistent-storage buckets are optionally gated by an **access list,** an ERC-721 soulbound NFT contract. If a wallet holds a token, it has read and write access to the bucket. If you only need private storage, skip this step and create the bucket without an access list.

**Create an access list**

```bash
npm run cli createAccessList <name> <symbol>
```

Capture the printed `Contract address: 0x…` — you will use it in the next steps.

**Add wallets**

```bash
npm run cli addToAccessList <contractAddress> <walletAddress>

# Add multiple wallets at once (comma-separated)
npm run cli addToAccessList <contractAddress> <addr1>,<addr2>
```

**Remove wallets**

```bash
npm run cli removeFromAccessList <contractAddress> <walletAddress>
```

**Check membership**

```bash
npm run cli checkAccessList <contractAddress> <walletAddress>
```

***

#### Bucket Commands

**Create a bucket**

```bash
# Private bucket (owner-only)
npm run cli createBucket

# Shared bucket gated by an access list
npm run cli createBucket <accessListAddress>
```

The output includes the **bucket ID** (UUID) and the owner address. Save the bucket ID, you need it for all file operations and to reference files in algorithms.

**List your buckets**

```bash
npm run cli listBuckets
```

**List files in a bucket**

```bash
npm run cli listFilesInBucket <bucketId>
```

Access is enforced by the node: only the owner or ACL members can list files.

**Upload a file**

```bash
npm run cli addFileToBucket <bucketId> ./my-file.txt

# Upload with a custom name
npm run cli addFileToBucket <bucketId> ./my-file.txt custom-name.txt
```

**Get a file object descriptor**

Returns the `nodePersistentStorage` object used by the compute engine to mount the file:

```bash
npm run cli getFileObject <bucketId> my-file.txt
# Output: { "type": "nodePersistentStorage", "bucketId": "...", "fileName": "my-file.txt" }
```

**Delete a file**

```bash
npm run cli deleteFile <bucketId> my-file.txt
```

***

#### End-to-End Example: Shared Bucket (Alice & Bob)

This walkthrough mirrors the demo in `test/storage.test.ts`. Alice creates a shared bucket; Bob, who is on the access list and does not own the bucket, but can list its files.

```bash
# --- Alice ---
export PRIVATE_KEY=<alice-private-key>

# 1. Create an access list and add both wallets
npm run cli createAccessList DemoACL DACL
# → Contract address: 0xACL...

npm run cli addToAccessList 0xACL <alice-addr>
npm run cli addToAccessList 0xACL <bob-addr>

# 2. Create a bucket gated by the ACL
npm run cli createBucket 0xACL
# → Bucket ID: <bucket-uuid>

# 3. Upload a file
echo "hello from alice" > alice-bob.txt
npm run cli addFileToBucket <bucket-uuid> ./alice-bob.txt

# 4. Inspect
npm run cli listBuckets
npm run cli listFilesInBucket <bucket-uuid>
npm run cli getFileObject <bucket-uuid> alice-bob.txt

# --- Bob (switch wallets) ---
export PRIVATE_KEY=<bob-private-key>

# Bob is on the ACL → read access granted
npm run cli listFilesInBucket <bucket-uuid>
# Same file appears: node confirmed Bob's ACL token

# --- Clean up (Alice) ---
export PRIVATE_KEY=<alice-private-key>
npm run cli deleteFile <bucket-uuid> alice-bob.txt
npm run cli listFilesInBucket <bucket-uuid>
# Listing is now empty
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.oncompute.ai/persistent-storage/publish-your-docs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.