The PyPositron Command Line Interface (CLI) provides commands to create, manage, and run your desktop applications.

positron <command> [arguments]

Display help information about the CLI.

positron help

Output: Shows all available commands and their descriptions.

Create a new PyPositron project with an interactive wizard.

positron create

Interactive Prompts:

• Project directory: Where to create the project (default: current directory)
• Project name: Name of your project (default: demo_project)
• Author name: Your name (optional)
• Project description: Brief description (optional)
• Virtual environment: Whether to create a venv (y/N)

What it creates:

• Project directory structure
• main_app.py - Main application file
• config.json - Project configuration
• views/index.html - HTML interface
• LICENSE - MIT license file
• Virtual environment (if requested)

Example:

positron create
# Follow the interactive prompts
cd my_awesome_app

Start the PyPositron application in the current project directory.

positron start [arguments]

Requirements:

• Must be run from a PyPositron project directory
• Project must contain main_app.py

Arguments: Additional arguments are passed to the Python application.

Example:

cd my_project
positron start

Install packages in the project's virtual environment.

positron install <package_names>

Arguments:

• package_names: One or more package names to install

Requirements:

• Must be run from a PyPositron project directory
• Project must have a virtual environment

Examples:

# Install a single package
positron install requests

# Install multiple packages
positron install requests numpy pandas

# Install with specific version
positron install requests==2.28.0

Activate the project's virtual environment.

positron activate

Requirements:

• Must be run from a PyPositron project directory
• Project must have a virtual environment

Note: This command prepares the environment activation script. You may need to run the generated activation command manually.

Create a virtual environment in an existing PyPositron project.

positron venv

Requirements:

• Must be run from a PyPositron project directory
• Virtual environment should not already exist

What it does:

• Creates a venv directory in the project
• Sets up an isolated Python environment
• Updates project configuration

Example:

cd existing_project
positron venv

positron <command> -h

This will show detailed help for the specific command (when available).

# Create a new project
positron create
# Enter "my_app" when prompted for project name
# Choose "y" for virtual environment

# Navigate to project
cd my_app

# Run the application
positron start

# If you have a project without venv
cd existing_project
positron venv

# Install additional packages
positron install requests beautifulsoup4

# Run the project
positron start

• 0: Success
• 1: General error
• 2: Invalid command or arguments

Currently, PyPositron doesn't use specific environment variables, but it respects standard Python environment variables like:

• PYTHONPATH: Python module search path
• VIRTUAL_ENV: Virtual environment path

1. Command not found

   # Make sure PyPositron is installed
   pip install py-positron
   # Or reinstall
   pip uninstall py-positron && pip install py-positron

2. Permission denied

   # On Unix systems, ensure the script is executable
   chmod +x $(which positron)

3. Module import errors

   # Check if you're in the right directory
   pwd
   ls  # Should show main_app.py for start command

4. Virtual environment issues

   # For macOS users, check the manual venv guide
   # https://github.com/itzmetanjim/py-positron/wiki/Manually-creating-a-venv

For more help, see the Troubleshooting Guide or visit our GitHub Issues.