The Atom Core CLI

The Atom Core CLI is a command-line interface tool for interacting with the Star Atlas SAGE on the Solana blockchain. It provides various commands for managing fleets, cargo, crafting, and other in-game operations.

• Installation
• Global Options
• Commands
• Advanced Usage

Installation

You can install atom using your preferred package manager:

pnpm

pnpm add -g @hexon-studio/atom-core

yarn

yarn global add @hexon-studio/atom-core

npm

npm install -g @hexon-studio/atom-core

Docker Installation

To install the Atom CLI using docker you need to setup docker first. Then run:

docker pull docker.io/hexonstudio/atom-core

Global Options

The CLI accepts different options based on the command type (query or exec). All options marked with (required) can be provided either as command line arguments or as environment variables.

Tip

You can use environment variables instead of command line options to avoid typing them every time. This is especially useful for sensitive information like API keys and wallet credentials.

Query Options

These options are available for all query commands:

• -p, --playerProfile <publicKey> - The public key of the player profile (required)
  • Env var: ATOM_PLAYER_PROFILE
• -r, --rpcUrl <rpcUrl> - The primary Solana RPC URL (required)
  • Env var: ATOM_RPC_URL
• --commonApiUrl <url> - Cache API endpoint for getting common game data fast
  • Env var: ATOM_COMMON_API_URL
• --loggingToken <token> - Cloud logging service token
  • Env var: ATOM_LOGGING_TOKEN

Exec Options

These options are available for all exec commands:

• -o, --owner <publicKey> - The public key of the player’s wallet (required)
  • Env var: ATOM_OWNER
• -k, --keypair <secretKey> - The secret key of hot wallet as base58 string (required)
  • Env var: ATOM_HOT_WALLET
• -w, --webhookUrl <webhookUrl> - Optional webhook URL for receiving events
  • Env var: ATOM_WEBHOOK_URL
• --webhookSecret <secret> - Secret for webhook authentication
  • Env var: ATOM_WEBHOOK_SECRET
• --contextId <id> - A context reference for webhook calls
• --heliusRpcUrl <url> - Optional Helius RPC URL for priority fees
  • Env var: ATOM_HELIUS_RPC_URL
• --feeMode <mode> - Helius fee mode: low, medium, or high (default: low)
• --feeLimit <limit> - Priority fee limit in microlamports
• --atlas-prime - Enable Atlas Prime usage
• --mipt, --max-ixs-per-transaction <number> - Max instructions per transaction (default: 5)

Note

Environment variables take precedence over command line options. This means if you set both, the environment variable value will be used.

Commands

The CLI is organized into two main command groups:

Query Commands

Recipe List

List all available crafting recipes:

atom query recipe-list

Fleet Info

Get information about a fleet:

atom query fleet <fleetNameOrAddress>

Profile Info

Display detailed information about a player profile:

atom query profile

Exec Commands

Fleet Management

Dock/Undock

Dock a fleet at a starbase:

atom exec dock <fleetNameOrAddress>

Undock a fleet from a starbase:

atom exec undock <fleetNameOrAddress>

Movement

Warp to a sector:

atom exec warp <fleetNameOrAddress> <targetSector>

Subwarp to a sector:

atom exec subwarp <fleetNameOrAddress> <targetSector>

Note

The targetSector param is a string representing the sector coordinates divided by a comma. For example: 30,40 is a valid target sector

Mining Operations

Start mining resources:

atom exec start-mining <fleetNameOrAddress> <resourceMint>

Stop mining operations:

atom exec stop-mining <fleetNameOrAddress>

Cargo Operations

Load Cargo

Load cargo into a fleet:

atom exec load-cargo <fleetNameOrAddress> --resources [resourceList]

Resource format: [resource_address,mode,amount,cargo_pod]

• Modes: fixed, max, min, min-and-fill
• Example: ResourceMint123,fixed,100,fuel_tank

Unload Cargo

Unload cargo from a fleet:

atom exec unload-cargo <fleetNameOrAddress> --resources [resourceList]

Resource format: [resource_address,mode,amount,cargo_pod]

• Modes: fixed, max
• Example: ResourceMint123,max,1000,cargo_pod

Crew Management

Load Crew

Load crew members into a fleet:

atom exec load-crew <fleetNameOrAddress> <crewAmount>

Unload Crew

Unload crew members from a fleet:

atom exec unload-crew <fleetNameOrAddress> <crewAmount> [--allow-unload-required-crew]

Caution

The --allow-unload-required-crew flag allows unloading crew members required for fleet operation. Use with caution.

Crafting Operations

Start Crafting

Start a crafting operation:

atom exec start-crafting --crewAmount <number> --quantity <number> --recipe <address> --sector <coords>

Stop Crafting

Stop a crafting operation:

atom exec stop-crafting --craftingId <id> --recipe <address> --sector <coords>

Resources

Resource Management

Resources in Atom Core can be loaded and unloaded from fleets using different modes and must be stored in appropriate cargo pods.

Resource Format

When specifying resources in commands, use the following format:

resource_address,mode,amount,cargo_pod

Example:

ResourceMint123,fixed,100,fuel_tank

Parameters:

• resource_address: The public key of the resource to load/unload
• mode: The loading/unloading mode to use
• amount: The quantity to load/unload (or threshold value for min/max modes)
• cargo_pod: The type of cargo pod to use

Loading Modes

When loading resources onto a fleet, you can specify different loading modes:

• fixed: Load exact amount specified
• max: Fill up to maximum capacity
• min: Load minimum required amount
• min-and-fill: Load minimum amount and fill remaining space if below threshold

Note

When using the min-and-fill mode, the amount parameter represents the minimum threshold. The system will load at least this amount and fill remaining space if below the threshold.

Unloading Modes

When unloading resources from a fleet:

• fixed: Unload exact amount specified
• max: Unload all available amount

Cargo Pods

Resources must be stored in appropriate cargo pods on the fleet. The type of cargo pod affects resource storage capacity and efficiency.

Available cargo pod types:

• cargo_hold: General purpose storage for most resources
• fuel_tank: Specialized storage for fuel resources
• ammo_bank: Specialized storage for ammunition resources

Tip

Each cargo pod type has different storage capacities and efficiency rates for different resource types. Choose the appropriate pod type based on the resources you plan to store.