Something went wrong. Try again.
A fully featured CLI used as an alternative to AppView applications (Bsky.app/mu.social)
Something went wrong. Try again.
TypeScript
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586import { GLOBAL_OPTIONS, type CommandSpec, type OptionSpec } from './command.ts';import { usageLine } from './help.ts';import { root } from './commands/index.ts';
// The command reference as Markdown, for the agent skill: generated from the// same tree the parser uses. Every runnable command declares whether it// writes (`writes` on its spec); this generator refuses to run while one// does not, so the classification cannot silently fall behind the commands.
function flag(option: OptionSpec): string { const value = option.type === 'boolean' ? '' : ` <${option.value ?? 'value'}>`; return `${option.short ? `-${option.short}, ` : ''}--${option.name}${value}`;}
function describe(option: OptionSpec): string { const extra: string[] = []; if (option.choices) extra.push(`one of: ${option.choices.join(', ')}`); if (option.type === 'list') extra.push('repeatable'); if (option.setting) extra.push(`setting ${option.setting}`); return `${option.description}${extra.length ? ` (${extra.join('; ')})` : ''}`.replace(/\|/g, '\\|');}
function writesLine(command: CommandSpec): string | undefined { if (command.writes === 'network') return '**Writes to the network.** It changes your account, or publishes something other people can see.'; if (command.writes === 'local') return "**Writes only on this machine.** It changes local state — sessions, config, the shell's startup file — and nothing on the network."; return undefined;}
export function reference(): string { const network: string[] = []; const local: string[] = []; const lines: string[] = [ '# atcli command reference', '', '<!-- Generated by `node tools/reference.ts` from the command tree. Do not edit by hand. -->', '', '## Which commands write', '', 'Every command reads unless it is listed here.', '', 'These write to the network: they change your account, or publish something other people can see. An agent should have its user\'s ok before running one, unless the user asked for that exact action:', '', ]; const visit = (path: CommandSpec[]) => { const command = path[path.length - 1]!; if (command.hidden) return; if (path.length > 1) { const name = ['atcli', ...path.slice(1).map((each) => each.name)].join(' '); if (command.run && command.writes === undefined) { throw new Error(`reference: ${name} does not say whether it writes — set writes: false, 'local' or 'network' on its spec`); } if (command.run && command.writes === 'network') network.push(`\`${name}\``); if (command.run && command.writes === 'local') local.push(`\`${name}\``); lines.push(`${'#'.repeat(Math.min(path.length + 1, 4))} \`${name}\``, '', `${command.summary}.`, ''); const writes = writesLine(command); if (writes) lines.push(writes, ''); if (name === 'atcli xrpc') lines.push('Whether it writes depends on the method: queries (GET) read, procedures (POST) write.', ''); if (command.aliases?.length) lines.push(`Also: ${command.aliases.map((alias) => `\`${alias}\``).join(', ')}.`, ''); if (command.default) lines.push(`Without a subcommand, runs \`${name} ${command.default}\`.`, ''); if (command.run) { lines.push('```', usageLine(path), '```', ''); for (const arg of command.args ?? []) lines.push(`- \`<${arg.name}>${arg.variadic ? '...' : ''}\`${arg.required ? '' : ' (optional)'}: ${arg.description}`); for (const option of (command.options ?? []).filter((each) => !each.hidden)) lines.push(`- \`${flag(option)}\`: ${describe(option)}`); if ((command.args ?? []).length || (command.options ?? []).length) lines.push(''); } } for (const sub of command.subcommands ?? []) visit([...path, sub]); }; visit([root]); lines.push( network.length ? `- ${network.join(', ')}.` : '- (none).', '', 'These write only on this machine — sessions, config, the shell\'s startup file. Nothing on the network changes:', '', local.length ? `- ${local.join(', ')}.` : '- (none).', '', 'And `atcli xrpc` does either, depending on the method: queries (GET) read, procedures (POST) write.', '', 'Every command also takes the global options:', '', ...GLOBAL_OPTIONS.map((option) => `- \`${flag(option)}\`: ${describe(option)}`), '', ); return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;}