· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·

CLI Reference

The Astral CLI (asl) is the primary interface for interacting with your repositories. This reference covers all available commands, their options, and usage examples.

---

Global Options

These options work with any command:

--help, -h      # Show help for any command
--version, -v   # Show version information
--verbose       # Show detailed output
--quiet, -q     # Suppress non-essential output

---

Repository Commands

asl init

Initialize a new Astral repository.

asl init [directory]

# Options:
  --bare          # Create a bare repository (no working directory)
  --template DIR  # Use a template directory

# Examples:
  asl init                    # Initialize in current directory
  asl init my-project         # Initialize in my-project/
  asl init --bare repo.asl    # Create bare repository

asl clone

Clone an existing repository.

asl clone <source> [destination]

# Options:
  --depth N       # Create a shallow clone with N commits
  --branch NAME   # Clone specific branch only

# Examples:
  asl clone https://github.com/user/repo.git
  asl clone ./local-repo ./backup

---

Basic Workflow

asl status

Show the working tree status.

asl status

# Options:
  --short, -s     # Show short format
  --porcelain     # Machine-readable output

# Example output:
#  M src/main.go        (modified)
#  A src/new-file.go    (added)
#  D src/old-file.go    (deleted)
#  ? untracked.txt      (untracked)

asl save

Save changes to the repository (Astral's unified add+commit).

asl save [options] [pathspec...]

# Options:
  -m, --message MSG   # Commit message (required)
  -a, --all           # Include all modified files (default)
  --only              # Only save specified files

# Examples:
  asl save -m "Add login feature"
  asl save -m "Fix bug" src/auth/login.go
  asl save --only -m "Config only" config/

asl diff

Show changes between commits, commit and working tree, etc.

asl diff [options] [commit] [-- path...]

# Options:
  --staged           # Show staged changes (for compatibility)
  --stat             # Show diffstat
  --name-only        # Only show file names

# Examples:
  asl diff                    # Working tree vs HEAD
  asl diff 8f2a1c3d           # Working tree vs commit
  asl diff 8f2a..4b1d         # Between two commits

---

Stack Commands

asl stack

Visualize the current stack.

asl stack [options]

# Options:
  --all, -a      # Show all stacks
  --oneline      # Compact output

# Example output:
#   @ 8f2a1c (HEAD) Add authentication
#   o 4b1d9e Implement login form
#   o 1a2b3c Setup database
#   |
#   o (main)

asl prev / asl next

Navigate the stack.

asl prev [N]    # Move N commits back (default: 1)
asl next [N]    # Move N commits forward (default: 1)

# Examples:
  asl prev          # Go to previous commit
  asl prev 3        # Go back 3 commits
  asl next          # Go to next commit

asl goto

Jump to a specific commit.

asl goto <commit>

# Examples:
  asl goto 8f2a1c3d
  asl goto HEAD~3

asl amend

Amend the current commit.

asl amend [options]

# Options:
  -m, --message MSG   # New commit message
  --no-edit           # Keep existing message

# Examples:
  asl amend -m "Better message"
  asl amend --no-edit   # Just add current changes

asl reorder

Interactively reorder commits.

asl reorder [options]

# Opens an editor to reorder, squash, or edit commits

asl squash

Squash commits together.

asl squash N        # Squash top N commits

# Examples:
  asl squash 3      # Combine top 3 into one

---

Branch Commands

asl branch

List, create, or delete branches.

asl branch [options] [name] [start-point]

# Options:
  -d, --delete NAME   # Delete a branch
  -m, --move OLD NEW  # Rename a branch
  -a, --all           # List all branches

# Examples:
  asl branch                    # List branches
  asl branch feature-auth       # Create branch
  asl branch -d old-feature     # Delete branch

asl switch

Switch branches.

asl switch <branch>

# Options:
  -c, --create NAME   # Create and switch

# Examples:
  asl switch main
  asl switch -c feature-new

---

Merge & Sync

asl merge

Merge branches.

asl merge <branch> [options]

# Options:
  --ff               # Fast-forward only
  --no-ff            # Force merge commit
  --squash           # Squash all commits
  --abort            # Abort current merge
  --continue         # Continue after resolving conflicts

# Examples:
  asl merge feature-auth
  asl merge feature --squash

asl resolve

Mark a file as resolved after conflict.

asl resolve <file>

# Examples:
  asl resolve src/config.go

---

History Commands

asl log

Show commit history.

asl log [options] [revision]

# Options:
  -n N               # Limit to N commits
  --oneline          # Compact format
  --graph            # Show ASCII graph
  --stat             # Show diffstat
  --author PATTERN   # Filter by author

# Examples:
  asl log -n 10
  asl log --oneline --graph
  asl log --author="john"

asl show

Show a commit.

asl show [commit]

# Examples:
  asl show              # Show HEAD
  asl show 8f2a1c3d     # Show specific commit

---

Utility Commands

asl cat-object

Display object contents.

asl cat-object [options] <object>

# Options:
  -t                 # Show type only
  -s                 # Show size only
  -p                 # Pretty-print content

# Examples:
  asl cat-object 8f2a1c3d
  asl cat-object -t 8f2a1c3d

asl hash-object

Compute hash of a file.

asl hash-object <file>

# Examples:
  asl hash-object README.md

asl gc

Run garbage collection.

asl gc [options]

# Options:
  --aggressive       # More thorough (slower)
  --prune            # Prune unreachable objects

---

Command Summary