Metadata-Version: 2.5
Name: scapps
Version: 26.9.0
Summary: The StratusCore Apps CLI tool for creating and running applications.
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# scapps

The StratusCore Apps CLI tool for creating and running applications.

## Highlights

- Scaffold containerized apps from templates (`scapps new --author <author> --ros2`)
- Wire up runtime features — ROS2 networking, reverse-proxy routing — with a single flag in `scapps.yaml`
- Declare app-to-app dependencies so `scapps run` starts sibling apps automatically
- Package and install images for air-gapped deployment with `scapps bundle` / `scapps install`

## Requirements

- [Docker](https://docs.docker.com/get-docker/) with the Compose plugin (`docker compose`)

## Getting Started

```bash
# create a new application (--author is required, see App Identity below)
scapps new my-app --author stratus

# run the application
scapps run my-app

# run all apps in a directory
scapps run example-apps

# check running applications
scapps info

# attach to application logs
scapps attach my-app

# stop the application
scapps down my-app
```

### Templates & Runtime Features

`scapps new` scaffolds an app from a template. Template flags like `--ros2` also enable **runtime features** — reusable blocks of Docker Compose config (host networking, reverse-proxy routing, etc.) that get generated into the app's compose file on `scapps run`.

```bash
scapps new my-ros-app --author stratus --ros2
```

See `docs/COMMANDS.md` in the repo (Template Option Flags section) to get started.

### App Identity

An app's real, globally-unique identity is its `name:` plus `author:` from `scapps.yaml`, not the bare `name:` alone — required so two different authors' apps can share a name without colliding.

```yaml
name: example-app
author: stratus
```

See `docs/COMMANDS.md` in the repo (App Identity section) to get started.

### App Dependencies

An app can declare other StratusCore apps it depends on, by their canonical `{author}.{name}` id. `scapps run` finds and starts any sibling dependency automatically before starting the app itself.

```yaml
name: my-app
dependencies:
  - stratus.my-app-dependency
```

See `docs/COMMANDS.md` in the repo (App Dependencies section) to get started.

### Offline & Air-Gapped Deployment

`scapps bundle` builds/pulls an app's images and packages them into a `.scapp` bundle named after its canonical id; `scapps install` loads that bundle on a machine with no internet access.

```bash
scapps bundle my-app                  # produces stratus.my-app.scapp
scapps install stratus.my-app.scapp   # loads it on the target machine
```

See `docs/COMMANDS.md` in the repo (`bundle` and `install` sections) to get started.

## Documentation

Full details on every command, option, template flag, and runtime feature live in `docs/COMMANDS.md` in the repo.

## Contributing

See `docs/CONTRIBUTING.md` in the repo for running tests, adding a template, or adding a runtime feature.
