Skip to content

CLI: File Operations

← CLI Reference | API Documentation

This document describes CLI commands for file manipulation operations and their Python API equivalents.

write - Write file content

Write content to a file. Creates parent directories automatically.

CLI: 

# Basic write
nexus write /workspace/file.txt "Hello World"

# Write from stdin
echo "Hello World" | nexus write /workspace/file.txt --input -

# Write from file
nexus write /workspace/file.txt --input local_file.txt

# Optimistic concurrency control
nexus write /doc.txt "Updated" --if-match abc123

# Create-only mode
nexus write /new.txt "Initial" --if-none-match

# Show metadata
nexus write /doc.txt "Content" --show-metadata

Python API: 

# Basic write
nx.write("/workspace/file.txt", b"Hello World")

# Write with metadata return
metadata = nx.write("/workspace/file.txt", b"Hello World")
print(f"ETag: {metadata['etag']}, Version: {metadata['version']}")

# Optimistic concurrency control
nx.write("/doc.txt", b"Updated", if_match="abc123")

# Create-only mode
nx.write("/new.txt", b"Initial", if_none_match=True)

# Write JSON
import json
data = {"key": "value"}
nx.write("/data/config.json", json.dumps(data).encode())

# Write binary
with open("image.jpg", "rb") as f:
    nx.write("/images/photo.jpg", f.read())

Options: - --input PATH: Read content from file or stdin (-) - --if-match ETAG: Only write if current ETag matches (optimistic locking) - --if-none-match: Only write if file doesn't exist (create-only) - --show-metadata: Display file metadata after write - --remote-url URL: Connect to remote server - --remote-api-key KEY: API key for authentication

See Also: - Python API: write() - Optimistic Concurrency Control

cat - Display file contents

Read and display file content.

CLI: 

# Read file
nexus cat /workspace/file.txt

# Show metadata (etag, version)
nexus cat /workspace/file.txt --metadata

# Time-travel: Read at historical operation point
nexus cat /workspace/file.txt --at-operation op_abc123

Python API: 

# Read file
content = nx.read("/workspace/file.txt")
text = content.decode("utf-8")

# Read with metadata
result = nx.read("/workspace/file.txt", return_metadata=True)
content = result["content"]
etag = result["etag"]
version = result["version"]

# Read JSON
import json
content = nx.read("/data/config.json")
data = json.loads(content.decode())

# Time-travel read
from nexus.core.permissions import OperationContext
ctx = OperationContext(at_operation="op_abc123")
content = nx.read("/workspace/file.txt", context=ctx)

Options: - --metadata: Show file metadata (etag, version, size, modified time) - --at-operation OP_ID: Read file at specific operation point (time-travel) - --remote-url URL: Connect to remote server - --remote-api-key KEY: API key for authentication

See Also: - Python API: read() - Time Travel

rm - Delete file

Delete a file from Nexus.

CLI: 

# Delete with confirmation
nexus rm /workspace/file.txt

# Force delete (no confirmation)
nexus rm /workspace/file.txt --force

Python API: 

# Delete file
nx.delete("/workspace/file.txt")

# Delete with specific user context
from nexus.core.permissions import OperationContext
ctx = OperationContext(user="alice", groups=["eng-team"])
nx.delete("/workspace/file.txt", context=ctx)

Options: - --force: Skip confirmation prompt - --remote-url URL: Connect to remote server - --remote-api-key KEY: API key for authentication

See Also: - Python API: delete()

cp/copy - Copy files

Copy a file to a new location.

CLI: 

# Simple copy
nexus cp /source.txt /dest.txt

# Smart copy with deduplication
nexus copy /source.txt /dest.txt

Python API: 

# Copy file
nx.copy("/source.txt", "/dest.txt")

# The copy operation is content-addressed and deduplicated automatically

Options: - --remote-url URL: Connect to remote server - --remote-api-key KEY: API key for authentication

See Also: - Python API: copy()

move - Move files

Move or rename a file.

CLI: 

# Move file
nexus move /old/path.txt /new/path.txt

Python API: 

# Move/rename file
nx.move("/old/path.txt", "/new/path.txt")

# Move with specific user context
from nexus.core.permissions import OperationContext
ctx = OperationContext(user="alice", groups=["eng-team"])
nx.move("/old/path.txt", "/new/path.txt", context=ctx)

Options: - --remote-url URL: Connect to remote server - --remote-api-key KEY: API key for authentication

See Also: - Python API: move()

Common Workflows

Basic file management

# Write a file
nexus write /docs/README.md "# My Project"

# Read it back
nexus cat /docs/README.md

# Copy it
nexus cp /docs/README.md /docs/README.backup.md

# Move it
nexus move /docs/README.backup.md /backups/README.md

# Delete it
nexus rm /backups/README.md --force

Python equivalent

import nexus

# Initialize
nx = nexus.Nexus(data_dir="./nexus-data")

# Write a file
nx.write("/docs/README.md", b"# My Project")

# Read it back
content = nx.read("/docs/README.md")
print(content.decode())

# Copy it
nx.copy("/docs/README.md", "/docs/README.backup.md")

# Move it
nx.move("/docs/README.backup.md", "/backups/README.md")

# Delete it
nx.delete("/backups/README.md")

See Also