AI And CLI Guide For SOAD Hub Users
A safe workflow for connecting AI coding agents and SOAD CLI to your SOAD Hub workspace.
1. What This Guide Is For
This guide explains how to connect an AI coding agent and SOAD CLI to your SOAD Hub workspace.
It does not replace the official SØAD documentation. For details about SØAD architecture, SOADMIN, transactions, database tools, built-in AI features, and framework examples, read:
2. What This Guide Covers
This guide focuses on:
- Using SOAD CLI with your SOAD Hub workspace.
- Letting an AI coding agent work safely with SOAD CLI.
- Pulling and pushing SØAD transactions.
- Asking the agent for clear, limited changes.
- Keeping secrets out of prompts and files.
For learning how SØAD itself works, use the official SØAD documentation.
3. AI And CLI Workflow Overview
The recommended workflow is:
- Create your workspace in SOAD Hub.
- Confirm SOADMIN login works.
- Install SOAD CLI on your computer.
- Start your AI coding agent in a local project folder.
- Log in to your workspace using SOAD CLI.
- Ask the agent to pull or create one transaction.
- Ask the agent to make a specific change.
- Review any SQL before running it in SOADMIN.
- Let the agent push only the intended transaction.
- Test the route in your browser.
4. Required Information
Prepare:
| Information | Example |
|---|---|
| Workspace URL | https://sh-customer-portal.soad.app |
| SOADMIN URL | https://sh-customer-portal.soad.app/s0adm/t/uac/login |
| Login email | developer@company.com |
| Transaction group | crm |
| Transaction code | customer |
| Feature goal | Customer management page |
Do not paste passwords, passphrases, API keys, or private tokens into normal chat messages.
5. SOAD CLI Login
Use your workspace base URL as the SOAD CLI server URL:
https://sh-<code-name>.soad.app
Example:
soad login --server https://sh-customer-portal.soad.app
The CLI may ask for:
- Email or username.
- Password.
- Passphrase if required.
Enter secrets only through the secure terminal prompt. Do not ask the agent to store secrets in files.
6. Optional Skill Bundle
If your AI coding agent supports skills or instruction bundles, use the SOAD Developer Skill Bundle from SOAD Hub:
The package helps the agent follow SØAD conventions and SOAD CLI workflow.
It includes:
- SOAD skill instructions.
- SOAD coding context.
- SOAD CLI workflow references.
- Transaction, view, SQL, HTMX, upload, and render guidance.
If your agent does not support skills, you can still use this guide and give the agent clear instructions manually.
The skill package does not need your workspace password. Do not add passwords, tokens, private keys, or API secrets into the skill files.
7. Prepare A Local Project Folder
Create a folder where the AI agent can work.
Example:
mkdir customer_portal_soad
cd customer_portal_soad
SOAD CLI will place transaction files under this local project folder.
8. First Prompt To The Agent
Use a clear first prompt:
Use the SOAD Developer skill if available.
My SOAD workspace URL is:
https://sh-customer-portal.soad.app
First, check that SOAD CLI is installed.
Then run:
soad login --server https://sh-customer-portal.soad.app
Ask me for username, password, and passphrase only through secure terminal input.
Do not store secrets in files.
After login, inspect the local project and wait for my feature request.
9. Safe AI Change Workflow
For each change, ask the agent to:
- Confirm the transaction group and code.
- Pull the transaction first if it may already exist.
- Create the transaction only if it does not exist.
- Edit only the needed files.
- Provide SQL before using new tables.
- Wait for you to run SQL in SOADMIN.
- Check the changed files.
- Push only the changed transaction.
- Tell you the browser route to test.
This keeps each change clear and reduces the chance of affecting unrelated work.
10. Database Changes
SOAD CLI manages transaction files. It does not automatically create or alter database tables.
When a table or column is needed, the agent should provide SQL.
You should:
- Open SOADMIN.
- Open the SQL query tool.
- Review the SQL.
- Run the SQL only if it matches your requirement.
- Tell the agent when the SQL is complete.
Back up important data before running destructive SQL such as DROP, TRUNCATE, or wide DELETE statements.
For details about SØAD database tools, read:
11. Example Prompt: Build One Feature
Use the SOAD Developer skill if available.
Workspace:
https://sh-customer-portal.soad.app
Transaction:
- Group: crm
- Code: customer
Goal:
Build a customer management page.
Workflow:
- Login with SOAD CLI first.
- Pull crm/customer first.
- Create it only if missing.
- Give me SQL before using a new table.
- Wait for me to run SQL.
- Verify files before pushing.
- Push only crm/customer.
- Tell me the route to test.
12. Example Prompt: Improve Existing Transaction
Use the SOAD Developer skill if available.
Improve this existing transaction:
- Group: sales
- Code: invoice
Changes:
- Pull the transaction first.
- Improve the list page layout.
- Add search by invoice number and customer name.
- Do not change unrelated transactions.
- Verify before pushing.
- Push only sales/invoice.
13. What To Tell The Agent Every Time
Include:
- Workspace URL.
- Transaction group.
- Transaction code.
- Goal.
- Whether the transaction already exists.
- Whether SQL has already been run.
- Whether the agent should push after verification.
Short pattern:
Use SOAD Developer skill if available.
Workspace: https://sh-<code-name>.soad.app
Group: <group>
Code: <code>
Goal: <what to build>
Workflow: login, pull first, create only if missing, verify, push only this transaction.
14. Safety Rules
- Do not paste passwords into normal chat.
- Do not store secrets in source files.
- Review SQL before running it.
- Back up important data before destructive SQL.
- Pull before editing existing transactions.
- Push only the transaction being changed.
- Test every route in the browser after push.
- Ask the agent to explain any change you do not understand.
15. Built-In SØAD AI
SØAD may also include built-in AI features inside SOADMIN.
Use the official SØAD documentation to learn those built-in features:
This SOAD Hub guide focuses on connecting external AI coding agents and SOAD CLI to your workspace.
16. Common Issues
SOAD CLI is missing
Install SOAD CLI first, then restart the agent session.
Login failed
Check:
- Workspace URL is correct.
- Workspace status is ready in SOAD Hub.
- Email and password are correct.
- The terminal supports interactive password input.
Transaction already exists
Do not create it again. Ask the agent to pull it:
soad pull <group>/<code>
Database table missing
Ask the agent for SQL, run it in SOADMIN, then tell the agent the table is ready.
I need to learn SØAD framework concepts
Open the official SØAD documentation:
17. Quick Start Checklist
- Create a workspace in SOAD Hub.
- Confirm SOADMIN login works.
- Install SOAD CLI.
- Prepare a local project folder.
- Start your AI coding agent in that folder.
- Log in with SOAD CLI.
- Give the agent one clear transaction request.
- Review and run SQL manually if needed.
- Let the agent push only the intended transaction.
- Test the browser route.