swadhin / opencodehub public

📝 docs: update cli

swadhinbiswas committed 3 months ago

ea811be

1 parent eddb415

commit ea811be

1 file changed

+694 -0

Files

docs

cli.md +694

Showing 1 changed file+694-0

docs/cli.md

▼docs/cli.md

+694-0

@@ -0,0 +1,694 @@
	1	+# OpenCodeHub CLI (och)
	2	+
	3	+The OpenCodeHub CLI (`och`) provides a GitHub CLI-like experience for interacting with OpenCodeHub from the command line.
	4	+
	5	+## Installation
	6	+
	7	+```bash
	8	+npm install -g opencodehub-cli
	9	+```
	10	+
	11	+## Quick Start
	12	+
	13	+```bash
	14	+# 1. Login to your server
	15	+och auth login --url http://your-server:3000
	16	+
	17	+# 2. Create a repository
	18	+och repo create my-project --description "My new project"
	19	+
	20	+# 3. Push your code
	21	+och repo push --branch main
	22	+```
	23	+
	24	+---
	25	+
	26	+## Authentication
	27	+
	28	+### `och auth login`
	29	+Login to OpenCodeHub.
	30	+
	31	+```bash
	32	+och auth login --url http://your-server:3000
	33	+```
	34	+
	35	+Options:
	36	+\| Option \| Description \|
	37	+\|--------\|-------------\|
	38	+\| `-u, --url <url>` \| OpenCodeHub server URL \|
	39	+\| `-t, --token <token>` \| Personal access token (non-interactive) \|
	40	+\| `--with-token` \| Authenticate using interactive token entry \|
	41	+\| `--ca-file <path>` \| Path to custom CA bundle (self-signed TLS) \|
	42	+\| `--insecure` \| Disable TLS certificate verification \|
	43	+
	44	+Examples:
	45	+```bash
	46	+# Interactive login
	47	+och auth login --url http://localhost:3000
	48	+
	49	+# Non-interactive with token
	50	+och auth login --url http://localhost:3000 -t och_xxxxx
	51	+
	52	+# Self-signed TLS
	53	+och auth login --url https://git.example.com --ca-file /path/to/ca.pem
	54	+```
	55	+
	56	+### `och auth logout`
	57	+Logout from OpenCodeHub.
	58	+
	59	+```bash
	60	+och auth logout
	61	+```
	62	+
	63	+### `och auth status`
	64	+Show current authentication status.
	65	+
	66	+```bash
	67	+och auth status
	68	+```
	69	+
	70	+---
	71	+
	72	+## Repository Management
	73	+
	74	+### `och repo create <name>`
	75	+Create a new repository on OpenCodeHub.
	76	+
	77	+```bash
	78	+och repo create my-project --description "A cool project"
	79	+```
	80	+
	81	+Options:
	82	+\| Option \| Description \|
	83	+\|--------\|-------------\|
	84	+\| `-d, --description <desc>` \| Repository description \|
	85	+\| `-p, --private` \| Make repository private \|
	86	+\| `--no-init` \| Don't initialize with README \|
	87	+
	88	+### `och repo clone <repo>`
	89	+Clone a repository from OpenCodeHub.
	90	+
	91	+```bash
	92	+och repo clone owner/repo
	93	+och repo clone owner/repo my-local-name
	94	+```
	95	+
	96	+Arguments:
	97	+\| Argument \| Description \|
	98	+\|----------\|-------------\|
	99	+\| `<repo>` \| Repository in `owner/name` format \|
	100	+\| `[destination]` \| Local directory name (optional) \|
	101	+
	102	+### `och repo push`
	103	+Push local repository to OpenCodeHub.
	104	+
	105	+```bash
	106	+och repo push
	107	+och repo push --branch main
	108	+och repo push --force
	109	+```
	110	+
	111	+Options:
	112	+\| Option \| Description \|
	113	+\|--------\|-------------\|
	114	+\| `-b, --branch <branch>` \| Branch to push \|
	115	+\| `-f, --force` \| Force push (overwrite remote) \|
	116	+
	117	+### `och repo list`
	118	+List your repositories.
	119	+
	120	+```bash
	121	+och repo list
	122	+```
	123	+
	124	+---
	125	+
	126	+## Git Operations
	127	+
	128	+### `och git init`
	129	+Initialize a repository for OpenCodeHub.
	130	+
	131	+```bash
	132	+och git init
	133	+och git init --url http://your-server:3000
	134	+```
	135	+
	136	+Options:
	137	+\| Option \| Description \|
	138	+\|--------\|-------------\|
	139	+\| `-u, --url <url>` \| OpenCodeHub server URL \|
	140	+
	141	+### `och git push`
	142	+Push to OpenCodeHub (shorthand for `repo push`).
	143	+
	144	+```bash
	145	+och git push
	146	+och git push --branch main --force
	147	+```
	148	+
	149	+### `och git sync`
	150	+Sync with remote (fetch + push).
	151	+
	152	+```bash
	153	+och git sync
	154	+och git sync --force
	155	+```
	156	+
	157	+Options:
	158	+\| Option \| Description \|
	159	+\|--------\|-------------\|
	160	+\| `-f, --force` \| Force push after sync \|
	161	+
	162	+---
	163	+
	164	+## Pull Requests
	165	+
	166	+### `och pr create`
	167	+Create a new pull request.
	168	+
	169	+```bash
	170	+och pr create
	171	+och pr create --title "feat: new feature" --base main
	172	+```
	173	+
	174	+Options:
	175	+\| Option \| Description \|
	176	+\|--------\|-------------\|
	177	+\| `-t, --title <title>` \| PR title \|
	178	+\| `-b, --base <branch>` \| Base branch \|
	179	+\| `-h, --head <branch>` \| Head branch \|
	180	+\| `-d, --description <desc>` \| PR description \|
	181	+
	182	+### `och pr list`
	183	+List pull requests.
	184	+
	185	+```bash
	186	+och pr list
	187	+och pr list --state open
	188	+```
	189	+
	190	+Options:
	191	+\| Option \| Description \|
	192	+\|--------\|-------------\|
	193	+\| `-s, --state <state>` \| Filter by state (open, closed, all) \|
	194	+
	195	+### `och pr view <number>`
	196	+View a pull request.
	197	+
	198	+```bash
	199	+och pr view 42
	200	+```
	201	+
	202	+### `och pr checkout <number>`
	203	+Checkout a pull request locally.
	204	+
	205	+```bash
	206	+och pr checkout 42
	207	+```
	208	+
	209	+### `och pr merge <number>`
	210	+Merge a pull request.
	211	+
	212	+```bash
	213	+och pr merge 42
	214	+```
	215	+
	216	+### `och pr close <number>`
	217	+Close a pull request.
	218	+
	219	+```bash
	220	+och pr close 42
	221	+```
	222	+
	223	+---
	224	+
	225	+## Stacked PRs
	226	+
	227	+### `och stack create <name>`
	228	+Create a new branch in the current stack.
	229	+
	230	+```bash
	231	+och stack create feature/child-1
	232	+```
	233	+
	234	+### `och stack submit`
	235	+Push stack and create/update PRs for all branches.
	236	+
	237	+```bash
	238	+och stack submit
	239	+```
	240	+
	241	+### `och stack sync`
	242	+Rebase stack on updated main.
	243	+
	244	+```bash
	245	+och stack sync
	246	+```
	247	+
	248	+### `och stack log`
	249	+Visualize stack tree.
	250	+
	251	+```bash
	252	+och stack log
	253	+```
	254	+
	255	+### `och stack status`
	256	+Show current stack and branch status.
	257	+
	258	+```bash
	259	+och stack status
	260	+```
	261	+
	262	+---
	263	+
	264	+## Issues
	265	+
	266	+### `och issue create`
	267	+Create a new issue.
	268	+
	269	+```bash
	270	+och issue create --title "Bug: something broken" --body "Description..."
	271	+```
	272	+
	273	+Options:
	274	+\| Option \| Description \|
	275	+\|--------\|-------------\|
	276	+\| `-t, --title <title>` \| Issue title \|
	277	+\| `-b, --body <body>` \| Issue body \|
	278	+\| `--labels <labels>` \| Comma-separated labels \|
	279	+
	280	+### `och issue list`
	281	+List issues.
	282	+
	283	+```bash
	284	+och issue list
	285	+och issue list --state open
	286	+```
	287	+
	288	+Options:
	289	+\| Option \| Description \|
	290	+\|--------\|-------------\|
	291	+\| `-s, --state <state>` \| Filter by state (open, closed, all) \|
	292	+
	293	+### `och issue view <number>`
	294	+View an issue.
	295	+
	296	+```bash
	297	+och issue view 42
	298	+```
	299	+
	300	+### `och issue close <number>`
	301	+Close an issue.
	302	+
	303	+```bash
	304	+och issue close 42
	305	+```
	306	+
	307	+---
	308	+
	309	+## Branches
	310	+
	311	+### `och branch checkout [branch]`
	312	+Checkout a branch (interactive if no branch specified).
	313	+
	314	+```bash
	315	+och branch checkout
	316	+och branch checkout main
	317	+```
	318	+
	319	+### `och branch rename [old-name] <new-name>`
	320	+Rename a branch.
	321	+
	322	+```bash
	323	+och branch rename old-name new-name
	324	+```
	325	+
	326	+---
	327	+
	328	+## Merge Queue
	329	+
	330	+### `och queue add <pr-number>`
	331	+Add a pull request to the merge queue.
	332	+
	333	+```bash
	334	+och queue add 42
	335	+```
	336	+
	337	+### `och queue list`
	338	+List merge queue items.
	339	+
	340	+```bash
	341	+och queue list
	342	+```
	343	+
	344	+### `och queue remove <pr-number>`
	345	+Remove a pull request from the merge queue.
	346	+
	347	+```bash
	348	+och queue remove 42
	349	+```
	350	+
	351	+---
	352	+
	353	+## CI/CD
	354	+
	355	+### `och ci list`
	356	+List pipeline runs.
	357	+
	358	+```bash
	359	+och ci list
	360	+```
	361	+
	362	+### `och ci view <run-id>`
	363	+View a pipeline run.
	364	+
	365	+```bash
	366	+och ci view run-123
	367	+```
	368	+
	369	+### `och ci cancel <run-id>`
	370	+Cancel a pipeline run.
	371	+
	372	+```bash
	373	+och ci cancel run-123
	374	+```
	375	+
	376	+---
	377	+
	378	+## Releases
	379	+
	380	+### `och release create <tag>`
	381	+Create a new release.
	382	+
	383	+```bash
	384	+och release create v1.0.0 --name "Version 1.0.0" --body "Release notes..."
	385	+```
	386	+
	387	+Options:
	388	+\| Option \| Description \|
	389	+\|--------\|-------------\|
	390	+\| `-n, --name <name>` \| Release name \|
	391	+\| `-b, --body <body>` \| Release notes \|
	392	+\| `--draft` \| Create as draft \|
	393	+\| `--prerelease` \| Mark as pre-release \|
	394	+
	395	+### `och release list`
	396	+List releases.
	397	+
	398	+```bash
	399	+och release list
	400	+```
	401	+
	402	+---
	403	+
	404	+## Code Review
	405	+
	406	+### `och review ai <pr-number>`
	407	+Trigger AI code review for a pull request.
	408	+
	409	+```bash
	410	+och review ai 42
	411	+```
	412	+
	413	+### `och review status <pr-number>`
	414	+Check AI review status.
	415	+
	416	+```bash
	417	+och review status 42
	418	+```
	419	+
	420	+---
	421	+
	422	+## Secrets
	423	+
	424	+### `och secret set <name>`
	425	+Set a secret.
	426	+
	427	+```bash
	428	+och secret set MY_SECRET
	429	+```
	430	+
	431	+### `och secret list`
	432	+List secrets.
	433	+
	434	+```bash
	435	+och secret list
	436	+```
	437	+
	438	+### `och secret delete <name>`
	439	+Delete a secret.
	440	+
	441	+```bash
	442	+och secret delete MY_SECRET
	443	+```
	444	+
	445	+---
	446	+
	447	+## Notifications
	448	+
	449	+### `och notify list`
	450	+List your notifications.
	451	+
	452	+```bash
	453	+och notify list
	454	+```
	455	+
	456	+### `och notify read [id]`
	457	+Mark notification(s) as read.
	458	+
	459	+```bash
	460	+och notify read
	461	+och notify read notification-id
	462	+```
	463	+
	464	+---
	465	+
	466	+## SSH Keys
	467	+
	468	+### `och ssh-key add`
	469	+Add an SSH key to your account.
	470	+
	471	+```bash
	472	+och ssh-key add
	473	+```
	474	+
	475	+### `och ssh-key list`
	476	+List your SSH keys.
	477	+
	478	+```bash
	479	+och ssh-key list
	480	+```
	481	+
	482	+### `och ssh-key delete <id>`
	483	+Delete an SSH key.
	484	+
	485	+```bash
	486	+och ssh-key delete key-id
	487	+```
	488	+
	489	+---
	490	+
	491	+## Search
	492	+
	493	+### `och search repos <query>`
	494	+Search repositories.
	495	+
	496	+```bash
	497	+och search repos "machine learning"
	498	+```
	499	+
	500	+### `och search issues <query>`
	501	+Search issues.
	502	+
	503	+```bash
	504	+och search issues "bug fix"
	505	+```
	506	+
	507	+---
	508	+
	509	+## Insights
	510	+
	511	+### `och insights show`
	512	+Show your developer metrics.
	513	+
	514	+```bash
	515	+och insights show
	516	+```
	517	+
	518	+### `och insights team`
	519	+Show team/repository metrics.
	520	+
	521	+```bash
	522	+och insights team
	523	+```
	524	+
	525	+---
	526	+
	527	+## Configuration
	528	+
	529	+### `och config list`
	530	+List all configuration values.
	531	+
	532	+```bash
	533	+och config list
	534	+```
	535	+
	536	+### `och config get <key>`
	537	+Get a configuration value.
	538	+
	539	+```bash
	540	+och config get serverUrl
	541	+```
	542	+
	543	+### `och config set <key> <value>`
	544	+Set a configuration value.
	545	+
	546	+```bash
	547	+och config set serverUrl http://localhost:3000
	548	+```
	549	+
	550	+---
	551	+
	552	+## Automations
	553	+
	554	+### `och automate list`
	555	+List automation rules for current repository.
	556	+
	557	+```bash
	558	+och automate list
	559	+```
	560	+
	561	+### `och automate create`
	562	+Create a new automation rule.
	563	+
	564	+```bash
	565	+och automate create
	566	+```
	567	+
	568	+---
	569	+
	570	+## Runner
	571	+
	572	+### `och runner config`
	573	+Configure a self-hosted runner interactively.
	574	+
	575	+```bash
	576	+och runner config
	577	+```
	578	+
	579	+---
	580	+
	581	+## API
	582	+
	583	+### `och api <endpoint>`
	584	+Make direct API requests.
	585	+
	586	+```bash
	587	+och api /api/user
	588	+och api /api/repos --method POST --data '{"name": "my-repo"}'
	589	+```
	590	+
	591	+Options:
	592	+\| Option \| Description \|
	593	+\|--------\|-------------\|
	594	+\| `-m, --method <method>` \| HTTP method (GET, POST, PUT, DELETE) \|
	595	+\| `-d, --data <data>` \| Request body (JSON) \|
	596	+
	597	+---
	598	+
	599	+## Focus Mode
	600	+
	601	+### `och focus`
	602	+Interactive stack and review cockpit.
	603	+
	604	+```bash
	605	+och focus
	606	+```
	607	+
	608	+A terminal UI for managing PRs, reviews, and merge queue.
	609	+
	610	+---
	611	+
	612	+## Shell Completions
	613	+
	614	+### `och completion`
	615	+Generate shell completions.
	616	+
	617	+```bash
	618	+# Bash
	619	+och completion > ~/.bashrc.d/och-completion.bash
	620	+
	621	+# Zsh
	622	+och completion > ~/.zsh/completions/_och
	623	+
	624	+# Fish
	625	+och completion --fish > ~/.config/fish/completions/och.fish
	626	+```
	627	+
	628	+---
	629	+
	630	+## Environment Variables
	631	+
	632	+\| Variable \| Description \|
	633	+\|----------\|-------------\|
	634	+\| `OCH_TOKEN` \| Personal access token (overrides config) \|
	635	+\| `OCH_SERVER_URL` \| Server URL (overrides config) \|
	636	+\| `OCH_HTTP_TIMEOUT_MS` \| HTTP request timeout (default: 15000) \|
	637	+
	638	+---
	639	+
	640	+## Configuration File
	641	+
	642	+The CLI stores configuration in `~/.config/opencodehub-cli/config.json`:
	643	+
	644	+```json
	645	+{
	646	+ "serverUrl": "http://localhost:3000",
	647	+ "token": "och_xxxxx",
	648	+ "username": "your-username"
	649	+}
	650	+```
	651	+
	652	+---
	653	+
	654	+## Common Workflows
	655	+
	656	+### New Repository
	657	+```bash
	658	+och auth login --url http://your-server:3000
	659	+mkdir my-project && cd my-project
	660	+git init
	661	+och repo create my-project --description "My project"
	662	+# Add files and commit
	663	+och repo push --branch main
	664	+```
	665	+
	666	+### Daily Development
	667	+```bash
	668	+och git sync # Pull latest changes
	669	+och branch checkout feature-x # Switch branch
	670	+# Make changes and commit
	671	+och git push # Push changes
	672	+och pr create --title "feat: X" # Create PR
	673	+```
	674	+
	675	+### Stacked PRs
	676	+```bash
	677	+och stack create feature/part-1 # Create first branch
	678	+# Work on part 1
	679	+och stack submit # Push & create PR
	680	+
	681	+och stack create feature/part-2 # Create child branch
	682	+# Work on part 2
	683	+och stack submit # Push & create PR
	684	+
	685	+och stack log # View stack hierarchy
	686	+```
	687	+
	688	+### Code Review
	689	+```bash
	690	+och pr list # See open PRs
	691	+och pr checkout 42 # Checkout PR branch
	692	+# Review code
	693	+och pr merge 42 # Merge when ready
	694	+```
0	695