Metadata-Version: 2.4
Name: dxlabs
Version: 0.1.9
Summary: A CLI tool by DX Labs to manage project assets, starting with .env on S3
Author-email: DX Labs <contact@dxlabs.io>
Requires-Python: >=3.9
Requires-Dist: boto3>=1.34.0
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: pyzipper>=0.3.6
Requires-Dist: rich>=13.7.0
Description-Content-Type: text/markdown

# dxlabs

A Python CLI tool by DX Labs to manage project assets. Currently supporting `.env` file management and incremental, encrypted workspace synchronization on AWS S3.

## Installation

```bash
pip install dxlabs
```

## Usage

### Initialize configuration

```bash
dxlabs init --bucket my-env-bucket --project my-project-name --profile my-aws-profile
```

### Push local .env to S3

```bash
dxlabs env push --env development
# or scan and push all discovered .env files
dxlabs env push
```

### Pull from S3 to local .env

```bash
dxlabs env pull --env staging
# or pull all files stored for the project
dxlabs env pull
```

### List environment files on S3

```bash
dxlabs env list
```

### Delete .env from S3

```bash
# Delete a specific environment
dxlabs env delete --env staging
# Delete a specific file path
dxlabs env delete --file .env.prod
# Delete ALL environment files for the project
dxlabs env delete --all
```

### Synchronize a whole project directory between machines

`dxlabs workspace` lets you carry a project directory between machines that
don't share a network (e.g. a work PC and a home PC) via S3, uploading only
what changed since the last push, encrypted with AES-256. Both commands
always operate on the current directory — run them from the root of the
project you're synchronizing.

```bash
# On the source machine: package + upload everything added/modified/deleted
# since the last push. You'll be prompted for an encryption password.
cd "D:\Projects\MyApp"
dxlabs workspace push

# On the destination machine: download and apply every pending package,
# in order, bringing the current directory in sync.
cd "D:\Projects\MyApp"
dxlabs workspace pull

# Preview what a push/pull would do, without uploading, downloading, or
# changing anything (still prompts for the password, since pull preview
# needs to decrypt each pending package's manifest to know what's inside).
dxlabs workspace push --preview
dxlabs workspace pull --preview
```

The password is never stored — it's requested via a hidden prompt on every
run. To automate `push`/`pull` non-interactively (e.g. in a script), set the
`DXLABS_WORKSPACE_PASSWORD` environment variable instead of the prompt. The
first push always packages the entire directory; subsequent pushes only
package the diff. State is tracked on S3 (so `push` can run from any
machine) plus a small local `.dxlabs.workspace-state.json` marker in the
current directory (so `pull` knows which packages it already applied) —
add it to `.gitignore`.

Unlike `env`, files are keyed by a random opaque `workspace_id` rather than
the project's name — `WORKSPACE/{workspace_id}/...` instead of
`WORKSPACE/{project}/...` — so guessing/knowing the project name alone isn't
enough to find it. This ID is generated once on `dxlabs init` and stored in
`.dxlabs.json`. Every push also leaves a single empty marker object under a
purely cosmetic sibling folder, `WORKSPACE/{workspace_id}-{project}/` — this
lets you tell which project a `workspace_id` folder belongs to when browsing
the S3 console, but no real data is ever stored there.

If `.dxlabs.json` doesn't have a `workspace_id` yet (e.g. it predates this
feature, or was never copied from the machine that ran `init`), `workspace
push`/`pull` refuse to run and print a suggested ID instead of silently
generating one — copy the existing `workspace_id` from the other machine if
this project was already pushed, otherwise add the suggested one.

## Features

- **Multi-Environment Support**: Specify environments like `dev`, `staging`, `prod`.
- **S3 Backend**: Secure storage in your own AWS S3 bucket with full S3 URI visibility.
- **Batch Operations**: Push or pull all environment files in one command.
- **CI/CD Integration**: Supports AWS environment variables for credentials.
- **Encrypted Workspace Sync**: Carry a whole project directory between machines via S3, uploading only incremental, AES-256 encrypted diffs.
