CLI Quick Start

Deploy your first application using the Clue2App CLI in under 5 minutes.

Prerequisites

• Python 3.9 or higher
• Git installed
• A GitHub account (for accessing repositories)

Installation

Install the Clue2App CLI using pip:

pip install clue2app-cli

Verify the installation:

c2a --version

Step 1: Login

Authenticate with your Clue2App account:

c2a login

This opens a browser window for authentication. After logging in, you'll see:

✅ Login successful!
   Welcome, your-email@example.com

Step 2: Create a Project

Projects organize your applications and determine where they're deployed.

c2a projects create --name "MyProject" --namespace "myproject"

Output:

✅ Project created successfully!
   Name: MyProject
   Namespace: myproject
   ID: abc123-def456-...

Namespace Rules

• Namespaces must be lowercase
• Use only letters, numbers, and hyphens
• The namespace appears in your app URLs: https://appname.myproject.apps.clue2.app

Step 3: Select Your Project

Set the project as your active context:

c2a projects use MyProject

Output:

✅ Active project set to: MyProject (myproject)

Verify your current context:

c2a config show

Step 4: Deploy Your Application

Deploy an application from a Git repository:

c2a apps create my-app \
  --git-url https://github.com/clue2solve/clue2app-fastapi-demo.git \
  --branch main

Output:

🚀 Creating application 'my-app'...
   📦 Git: https://github.com/clue2solve/clue2app-fastapi-demo.git (main)
   📁 Project: MyProject
✅ Application created successfully!
   📋 The application will be built and deployed automatically.

Step 5: Monitor Your Deployment

Check the build status:

c2a apps list

Output:

╭─ Apps Summary ──╮
│ Project: MyProject │
╰─────────────────╯

                    Applications
┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
┃ Name     ┃ Project   ┃ Status  ┃ Builds ┃ Branch ┃
┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
│ my-app   │ MyProject │ ✓ Ready │   1    │ main   │
└──────────┴───────────┴─────────┴────────┴────────┘

Step 6: Access Your Application

Once the status shows ✓ Ready, your app is live at:

https://my-app.myproject.apps.clue2.app

View application logs:

c2a apps logs my-app

Common Commands Reference

Command	Description
c2a login	Authenticate with Clue2App
c2a logout	Log out of your account
c2a projects list	List all your projects
c2a projects use <name>	Switch to a project
c2a apps list	List apps in current project
c2a apps create <name>	Create and deploy a new app
c2a apps show <name>	Show app details
c2a apps logs <name>	View application logs
c2a apps rebuild <name>	Trigger a rebuild
c2a apps delete <name>	Delete an application

Using Private Repositories

Clue2App supports deploying from private Git repositories. You have two options:

Option 1: Automatic (Using GitHub CLI)

If you have the GitHub CLI installed and authenticated, the Clue2App CLI will automatically use your credentials:

# First, authenticate with GitHub CLI (one-time setup)
gh auth login

# Then create your app - credentials are detected automatically
c2a apps create my-private-app \
  --git-url https://github.com/myorg/private-repo.git \
  --branch main

Option 2: Explicit Credentials (Using Personal Access Token)

For more control or when gh CLI isn't available, provide credentials explicitly using a GitHub Personal Access Token (PAT).

Creating a GitHub Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens

2. Click "Generate new token"

3. Configure your token:

   • Token name: clue2app-deploy (or any descriptive name)
   • Expiration: Choose based on your security requirements
   • Repository access: Select "Only select repositories" and choose the repos you want to deploy

4. Required permissions (under Repository permissions):

   Permission	Access Level	Why it's needed
   Contents	Read-only	To clone and read your source code
   Metadata	Read-only	Required for all tokens (auto-selected)

5. Click "Generate token" and copy the token immediately (it won't be shown again)

Keep Your Token Secure

• Never commit tokens to your repository
• Store tokens securely (use environment variables or a secrets manager)
• Rotate tokens periodically
• Use fine-grained tokens with minimal permissions

Using Your Token

c2a apps create my-private-app \
  --git-url https://github.com/myorg/private-repo.git \
  --branch main \
  --git-username your-github-username \
  --git-token ghp_xxxxxxxxxxxxxxxxxxxx

Using Environment Variables (Recommended)

For better security, set credentials as environment variables:

export GIT_USERNAME="your-github-username"
export GIT_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

c2a apps create my-private-app \
  --git-url https://github.com/myorg/private-repo.git \
  --branch main \
  --git-username $GIT_USERNAME \
  --git-token $GIT_TOKEN

Classic Tokens (Alternative)

If you prefer classic tokens, create one at GitHub Settings → Personal access tokens (classic):

• Select the repo scope (Full control of private repositories)

Which Token Type?

• Fine-grained tokens (recommended): More secure, scoped to specific repos
• Classic tokens: Simpler setup, broader access

Next Steps

• Configure environment variables for your apps
• Set up custom domains
• Learn about the Console UI for visual management

Troubleshooting

Build Failed

Check the build logs:

c2a apps show my-app

App Not Accessible

Verify the app status is Ready:

c2a apps list

Authentication Issues

Re-authenticate:

c2a logout
c2a login

---

Need help? Visit our GitHub Issues or contact support.