---
id: planets
title: Planet Commands
sidebar_label: Planets
sidebar_position: 6
---

# Planet Commands

Planetary position and visibility calculations.

## Supported Planets

| Planet | Symbol | Alias |
|--------|--------|-------|
| Mercury | ☿ | `mercury` |
| Venus | ♀ | `venus` |
| Mars | ♂ | `mars` |
| Jupiter | ♃ | `jupiter` |
| Saturn | ♄ | `saturn` |
| Uranus | ⛢ | `uranus` |
| Neptune | ♆ | `neptune` |

## Commands

### `starward planets position <planet>`

Position of a specific planet.

```bash
starward planets position mars
starward planets position jupiter --jd 2451545.0
```

Output includes:
- Equatorial coordinates (RA/Dec)
- Distance from Earth and Sun
- Apparent magnitude
- Elongation from Sun
- Phase/illumination

### `starward planets all`

Summary of all planetary positions.

```bash
starward planets all
```

### `starward planets rise <planet>`

Planet rise time.

```bash
starward planets rise jupiter --lat 40.7 --lon -74.0
starward planets rise mars --observer home
```

### `starward planets set <planet>`

Planet set time.

```bash
starward planets set saturn --lat 40.7 --lon -74.0
```

### `starward planets transit <planet>`

Meridian transit time (when planet is highest).

```bash
starward planets transit jupiter --lat 40.7 --lon -74.0
```

### `starward planets altitude <planet>`

Current altitude of a planet.

```bash
starward planets altitude mars --lat 40.7 --lon -74.0
```

## Examples

```bash
# Quick overview using alias
starward p all

# Mars position with verbose calculation
starward planets position mars --verbose

# JSON for scripting
starward planets position jupiter --json | jq '.magnitude'

# Best time to observe Saturn
starward planets transit saturn --lat 34.05 --lon -118.25

# Check if Jupiter is up
starward planets altitude jupiter --lat 40.7 --lon -74.0
```

## Understanding the Output

### Elongation

The angular distance from the Sun:
- **0°** — Conjunction (behind or in front of Sun)
- **90°** — Quadrature (quarter phase for inner planets)
- **180°** — Opposition (best viewing for outer planets)

### Magnitude

Apparent brightness (lower = brighter):
- Venus: typically -4 to -3
- Jupiter: typically -2 to -1
- Saturn: typically +1 to +2
- Uranus: typically +5 to +6
- Neptune: typically +8

## Python API

```python
from starward import Planet, planet_position, all_planet_positions
from starward.core.planets import planet_rise, planet_altitude
from starward.core.observer import Observer

# Single planet
mars = planet_position(Planet.MARS)
print(f"Mars: RA {mars.ra.format_hms()}, Mag {mars.magnitude:+.1f}")

# All planets
positions = all_planet_positions()
for planet, pos in positions.items():
    print(f"{planet.value}: {pos.elongation.degrees:.1f}° from Sun")

# Rise time
observer = Observer.from_degrees("Home", 40.7, -74.0)
rise = planet_rise(Planet.JUPITER, observer)
if rise:
    print(f"Jupiter rises: {rise.to_datetime()}")
```
