zenith-docs/docs/command-reference/urbit.md

# Urbit Commands

Command reference for Urbit operations relevant to Zenith network participation, including ship management, desk installation, and network configuration.

!!! info "Official Urbit Documentation"
    For comprehensive Urbit command reference, see the [official Urbit documentation](https://urbit.org/using/os/dojo). This page focuses on Zenith-specific usage patterns.

## Installation and Setup

### Urbit Binary Installation
```bash
# Linux installation
curl -L https://urbit.org/install-linux | bash

# macOS installation  
curl -L https://urbit.org/install-macos | bash

# Verify installation
./urbit --version
```

### Ship Boot and Management
```bash
# Boot new ship with keyfile
./urbit -w <ship-name> -k <keyfile>

# Boot existing ship
./urbit <pier-directory>

# Boot with specific port
./urbit -p 8080 <pier-directory>

# Boot in daemon mode (background)
./urbit -d <pier-directory>
```

## Zenith-Specific Configuration

### Zenith Desk Installation
```bash
# Inside Urbit dojo (ship command line)
# Install zenith desk (commands may vary based on current implementation)
|install ~zod %zenith

# Mount desk for development
|mount %zenith

# Sync desk updates  
|sync %zenith
```

### Network Configuration
```bash
# Configure connection to Zenith network
# (Specific configuration commands to be documented)

# Set network endpoints
# (Configuration details to be documented)
```

## Ship Management Commands

### Inside Urbit Dojo
The Urbit dojo is the command-line interface within your ship. Access it by running your ship and using the prompt.

#### Basic Ship Operations
```urbit
# Check ship status
+trouble

# Check network connectivity
.^(@ud %j /=local=/bound)

# List installed desks
+trouble %desk

# Check pier information
+trouble %pier
```

#### Desk Management
```urbit
# List available desks
|show %desks

# Install desk from remote ship
|install ~<ship> %<desk>

# Update desk
|sync %<desk>

# Mount desk to Unix filesystem
|mount %<desk>

# Commit changes from Unix filesystem
|commit %<desk>
```

#### Network Operations
```urbit
# Check network connections
.^(path %j /=local=/bound)

# Reset network connection
|reset

# Clear ship cache
|reset %networking
```

### Ship Maintenance
```urbit
# Check ship health
+trouble

# Pack ship (optimize storage)
|pack

# Backup ship state
# (Performed at Unix level, not in dojo)

# Update ship runtime
|ota ~zod %kids
```

## Zenith Integration Commands

!!! warning "Development Status"
    Zenith-specific Urbit commands are under development. Check the [Zenith desk repository](https://github.com/Zenith-Foundation/zenith-desk) for current command reference.

### Transaction Submission
```urbit
# Submit transaction to star (conceptual)
:zenith|submit-tx <transaction-data>

# Check transaction status
:zenith|tx-status <tx-id>
```

### Network Participation
```urbit
# Check Zenith network status
:zenith|network-status

# Configure star connection
:zenith|set-star ~<star-ship>

# View participation status
:zenith|my-status
```

### Application Interaction
```urbit
# List Zenith applications
:zenith|list-apps

# Launch Zenith application
:zenith|launch <app-name>

# Check application status
:zenith|app-status <app-name>
```

## Development Commands

### Desk Development
```urbit
# Create new desk
|new-desk %my-desk

# Copy existing desk  
|new-desk %my-desk our %base

# Publish desk changes
|public %my-desk

# Set desk permissions
|perms %my-desk [%read %self]
```

### Testing and Debugging
```urbit
# Test desk functionality
:test %my-desk

# Debug desk issues
+trouble %desk %my-desk

# View desk files
+ls %/my-desk
```

## Administrative Operations

### Ship Security
```urbit
# Change ship password
|pass <new-password>

# Generate new authentication code
|code

# List active sessions
+sessions

# Revoke session
+revoke <session-id>
```

### System Configuration
```urbit
# Set ship timezone
|timezone 'US/Pacific'

# Configure HTTP settings
|http-server %start

# Set CORS permissions
|cors-approve '<domain>'
```

### Backup and Recovery
```bash
# Backup ship at Unix level (ship must be stopped)
tar -czf ship-backup-$(date +%Y%m%d).tar.gz <pier-directory>

# Restore ship from backup
tar -xzf ship-backup-<date>.tar.gz

# Boot restored ship
./urbit <restored-pier-directory>
```

## Network Integration

### Star-Planet Communication
```urbit
# Check sponsorship status
.^(unit ship %j /=sponsor=/our)

# Request sponsorship from star
# (Typically handled through Urbit Bridge)

# Configure network routing
# (Usually automatic, but can be debugged)
```

### Galaxy-Star Communication
```urbit
# Check galaxy connection
.^(unit ship %j /=galaxy=/our)

# Verify routing to galaxy
+ping ~<galaxy>

# Check network routes
.^(set ship %j /=peers=)
```

## Monitoring and Diagnostics

### Performance Monitoring
```urbit
# Check ship memory usage
+heap

# Monitor network activity
+verb %j

# Check event log
+vats

# Performance statistics
+mass
```

### Network Diagnostics
```urbit
# Test connectivity to specific ship
+ping ~<target-ship>

# Check NAT configuration
.^(@p %j /=local=/nat)

# Network trace information
+verb %ames
```

### Log Analysis
```bash
# View ship logs (Unix level)
tail -f <pier-directory>/.urb/log

# Filter for specific events
grep "zenith" <pier-directory>/.urb/log

# Analyze network events
grep "ames" <pier-directory>/.urb/log
```

## Troubleshooting

### Common Issues

#### Ship Boot Problems
```urbit
# Reset ship networking
|reset %networking

# Clear caches
|meld

# Rebuild from checkpoint
|pack
```

#### Network Connectivity
```urbit
# Test basic connectivity
+ping ~zod

# Reset network stack
|reset

# Check firewall and port configuration
# (Performed at Unix level)
```

#### Desk Installation Issues
```urbit
# Clear desk cache
|reset %clay

# Reinstall desk
|nuke %<desk>
|install ~<source> %<desk>
```

### Performance Issues
```urbit
# Optimize ship storage
|pack

# Clear unnecessary data
|meld

# Monitor resource usage
+mass
```

## Integration Examples

### Zenith Network Participation
```bash
# 1. Boot ship with proper configuration
./urbit -p 8080 my-ship

# 2. Install zenith desk (in dojo)
|install ~zod %zenith

# 3. Configure network connection
:zenith|configure <network-settings>

# 4. Submit attestation (conceptual)
:zenith|attest <attestation-data>
```

### Development Workflow
```bash
# 1. Mount desk for development
|mount %zenith

# 2. Edit files in Unix
nano <pier>/zenith/<file>

# 3. Commit changes
|commit %zenith

# 4. Test functionality
:test %zenith
```

## Resources

### Official Documentation
- **Urbit Documentation**: [urbit.org/using](https://urbit.org/using)
- **Dojo Reference**: [urbit.org/using/os/dojo](https://urbit.org/using/os/dojo)
- **Developer Guide**: [urbit.org/guides/core/hoon-school](https://urbit.org/guides/core/hoon-school)

### Zenith-Specific Resources
- **Zenith Desk**: [GitHub Repository](https://github.com/Zenith-Foundation/zenith-desk)
- **Integration Guide**: [App Development](../documentation/app-development.md)
- **Network Participation**: [Roles & Responsibilities](../overview/roles-responsibilities.md)

### Community Support
- **Urbit Community**: Official support channels and forums
- **Zenith Developers**: Zenith-specific development support
- **Stack Overflow**: Programming questions and solutions

!!! note "Evolving Commands"
    Zenith-specific Urbit commands are actively being developed. Check the latest desk releases and documentation for updated command reference and usage patterns.