okama-* CLI Reference

The main OkamaOS administration tool. Manages installed games, controllers, Bluetooth devices, and system status. Available in both normal mode and developer mode.

Status & Info

okama-cli status              # print OS version, channel, storage usage
okama-cli version             # print short version string

Game Management

okama-cli install <path>      # install a .ok package from path or URL
okama-cli list                # list installed games with ID, version, size
okama-cli run <game-id>       # launch a game by reverse-DNS ID
okama-cli remove <game-id>    # uninstall a game (backs up first)
okama-cli info <game-id>      # show manifest and install path for a game

Example:

okama-cli install /media/usb/mygame.ok
okama-cli list
# com.okamalabs.demo    v0.1.1   13 KB
# com.mypub.mygame      v1.0.0   840 KB

okama-cli run com.okamalabs.demo
okama-cli remove com.mypub.mygame

Controller Commands

okama-cli controllers list            # list connected and paired controllers
okama-cli controllers test            # stream live input events (Ctrl+C to stop)
okama-cli controllers default <id>   # set preferred controller by index

Bluetooth Commands

okama-cli bluetooth status            # check adapter power state
okama-cli bluetooth scan              # scan 15 s, print found devices
okama-cli bluetooth pair <mac>        # pair device; auto-trusts
okama-cli bluetooth trust <mac>       # mark device as trusted
okama-cli bluetooth connect <mac>     # connect immediately
okama-cli bluetooth disconnect <mac>  # disconnect without forgetting
okama-cli bluetooth forget <mac>      # remove from paired list

Update Subcommands

Quick aliases — full control is via okama-update:

okama-cli update check        # check for latest OS update
okama-cli update list         # list downloaded .okupdate bundles

Builds, inspects, verifies, and bundles .ok game packages. Use on your development machine to package games before distributing or testing on a device. Okama Studio uses a browser-native equivalent (JSZip).

Build a Package

# Auto-detect entry and runtime from directory
okama-pack build ./games/mygame

# Explicit output path
okama-pack build ./games/mygame --output mygame.ok

The tool reads manifest.ok.json from the game directory. If no manifest exists, use okama-agent auto-pack to generate one automatically.

Inspect Contents

okama-pack inspect mygame.ok   # list archive contents + manifest summary

Verify a Package

okama-pack verify mygame.ok    # validate manifest fields and archive integrity

Exits 0 on success. Prints each failing rule on error.

Bundle Python Dependencies

Use bundle to pip-install python_deps from the manifest into the game's site-packages/ directory for fully self-contained packaging:

okama-pack bundle ./games/mygame   # installs python_deps into site-packages/
okama-pack build ./games/mygame    # then build the self-contained .ok

Checks for, downloads, applies, and rolls back OS update bundles (.okupdate). Every apply backs up replaced files before writing new ones. User data is never touched.

Check for Updates

okama-update check
# Fetches updates/feed.json from STORE_URL (default: this portal)
# Prints: current version, latest version, and download URL if newer

Apply an Update

# Dry run first — inspect every file that will be replaced
okama-update apply --dry-run okamaos-v1.3.0.okupdate

# Apply with SHA-256 verification (recommended)
okama-update apply --sha256 7311537148ec04ca436bb21fd31ee115a412fcd33cc9a2c3420077b46928666b \
  okamaos-v1.3.0.okupdate

# Apply without hash check (dev use only)
okama-update apply okamaos-v1.3.0.okupdate

Allowed update targets: usr/bin/okama-*, usr/lib/okamaos/, usr/share/okamaos/, etc/init.d/S*, boot assets. Everything else is refused.

Rollback

okama-update rollback          # restore the most recent pre-apply backup

Backups are stored under /var/okamaos/updates/backups/ with timestamps.

Installs OkamaOS to a hard drive or sets up live USB persistence. Always prompts for confirmation before writing. Use --dry-run to preview every action before committing.

Hard-Drive Install

# Interactive install to /dev/sda (replace with your target device)
okama-install --target /dev/sda --dry-run   # preview first
okama-install --target /dev/sda --yes       # write after confirmation

Warning: this overwrites the entire target device. Run lsblk first to confirm the correct device path.

Live USB Persistence

Creates an OKAMA_DATA ext4 partition on an attached drive. On next boot the system mounts it at /var/okamaos, preserving games, saves, and config across reboots:

okama-install --make-persistence /dev/sdXN --dry-run
okama-install --make-persistence /dev/sdXN --yes

Check Persistence Status

okama-install --persistence-status
# Reports: mounted persistence partition (if any), path, and size

The game lifecycle manager. Called by okama-shell when a user selects a game. Acquires the game lock, validates the manifest, suspends non-essential services, launches the game process, and recovers on crash.

Manual Launch

okama-run <game-id>
# Example:
okama-run com.okamalabs.demo

Launch Sequence

• Acquires /var/run/okama-game.lock
• Validates manifest.ok.json (runtime, permissions, etc.)
• Checks controller requirement (rejects if controller_required=true and no gamepad found)
• Suspends non-essential background services
• Launches: python3 <entry> in fullscreen SDL2 mode
• On exit or crash: releases lock, resumes services, restores shell

Environment Injected into Games

PYTHONPATH   ← game's site-packages/ + lib/ + system /usr/lib/okamaos
OKAMA_GAME_ID ← reverse-DNS ID
OKAMA_SAVE_DIR ← /var/okamaos/saves/<game-id>
OKAMA_DATA_DIR ← /var/okamaos/games/<game-id>

The fullscreen SDL2/Pygame controller UI. Normally started by S99okama-shell on tty1 at boot. Respawns automatically on crash. Exposes Play, Settings (Controllers, Bluetooth, Audio, Network, Storage, Updates, Developer), and Power sections.

Developer Flags (host / dev mode)

okama-shell --windowed         # run in a desktop window (host dev)
okama-shell --no-controller    # allow keyboard-only mode
okama-shell --loglevel debug   # verbose logging to stdout

Settings Sections

The central controller daemon. Runs as a background service (S30okama-inputd). All consumers — shell and games — read from a single Unix socket. No game code ever touches evdev directly.

Socket

/run/okama-inputd.sock   ← newline-delimited JSON event stream

CLI Flags

okama-inputd               # normal daemon mode (started by init)
okama-inputd --test        # print live events to stdout (dev/debug)
okama-inputd --list        # list detected /dev/input/event* devices

Controller Profile Lookup Order

• Exact vendor+product match from /etc/okamaos/controller-profiles.json
• Bus-type match (usb / bluetooth)
• generic-usb-hid fallback (covers most standard HID gamepads)

Axis Dead Zone

Axis values within ±0.08 are zeroed before broadcast to prevent drift noise from reaching games and the shell.

Testing Controllers

okama-inputd --test          # stream all unified events
okama-cli controllers list   # show detected gamepads
okama-cli controllers test   # alias for above

Command-line AI agent for automating game packaging. The auto-pack subcommand analyses any game directory, auto-detects entry point, runtime, and dependencies, generates a manifest, bundles deps, and produces a ready-to-install .ok in one command.

Auto-Pack a Game

okama-agent auto-pack ./path/to/mygame
# Detects: main.py / game.py / index.html as entry point
# Parses:  requirements.txt / pyproject.toml / setup.py for deps
# Infers:  runtime from pygame/sdl2 imports
# Writes:  manifest.ok.json (if missing), builds mygame.ok

What auto-pack detects

• Entry point: scans for main.py, game.py, index.html
• Runtime: okama-sdl2 if pygame/sdl2 found, else okama-python
• Python deps: parsed from requirements.txt, pyproject.toml, or setup.py
• Target FPS: inferred from clock.tick(N) calls

Okama Studio Integration

Okama Studio (browser IDE) includes a full agentic AI that can call 9 tools: write_file, read_file, delete_file, list_files, search_files, commit, create_branch, create_issue, and run_preview. See Studio docs for the full tool reference.

The interactive developer console is a PTY-backed persistent shell session embedded in the OkamaOS Settings → Developer screen. Available only in developer mode. Supports long-running commands, interactive prompts (okama-install, etc.), and streaming output.

Enabling Dev Mode

Navigate to Settings → Developer in okama-shell. Enter the parent PIN to enable. Once active, the Dev Console tab appears and tty2 is unlocked.

Console Behaviour

• PTY-backed — interactive commands work (no stdin stall)
• Long-running command progress streams in real time
• ANSI escape codes stripped (TERM=dumb, NO_COLOR=1)
• Long input tail-scrolls with … prefix

Useful Dev Console Commands

# System info
okama-cli status
cat /etc/okamaos/okama.conf
free -m
df -h /var/okamaos

# Game management
okama-cli list
okama-cli install /media/usb/mygame.ok
okama-cli remove com.mypub.mygame

# OS updates
okama-update check
okama-update apply --dry-run /var/okamaos/updates/downloads/okamaos-v1.3.0.okupdate
okama-update apply okamaos-v1.3.0.okupdate
okama-update rollback

# Controllers
okama-inputd --test
okama-cli controllers list
okama-cli bluetooth scan
okama-cli bluetooth pair AA:BB:CC:DD:EE:FF

# Logs
cat /var/okamaos/logs/shell.log
cat /var/okamaos/logs/game-crash.log
journalctl -n 50   # if systemd is available

# Persistence / install
okama-install --persistence-status
lsblk

Accessing tty2

With developer mode active, press Ctrl+Alt+F2 (or equivalent) to switch to tty2, which runs a standard BusyBox getty shell. Return to the UI with Ctrl+Alt+F1.

Running okama-install from the Console

Because the console is PTY-backed, okama-install's interactive confirmation prompts work correctly. Type your response when prompted:

okama-install --target /dev/sdb --dry-run
# Review output, then:
okama-install --target /dev/sdb --yes