@agentuity/cli 0.0.59 → 0.0.61

package/src/cmd/cloud/domain.ts

@@ -1,5 +1,6 @@
 import * as dns from 'node:dns';
 import type { Config } from '../../types';
+import { StructuredError } from '@agentuity/core';
 
 export interface DNSResult {
 	domain: string;
@@ -7,6 +8,13 @@ export interface DNSResult {
 	message?: string;
 }
 
+const timeoutMs = 5000;
+
+const DNSTimeoutError = StructuredError(
+	'DNSTimeoutError',
+	`DNS lookup timed out after ${timeoutMs}ms`
+);
+
 /**
  * This function will check for each of the custom domains and make sure they are correctly
  * configured in DNS
@@ -31,12 +39,11 @@ export async function checkCustomDomainForDNS(
 	return Promise.all(
 		domains.map(async (domain) => {
 			try {
-				const timeoutMs = 5000;
 				let timeoutId: Timer | undefined;
 
 				const timeoutPromise = new Promise<never>((_, reject) => {
 					timeoutId = setTimeout(() => {
-						reject(new Error(`DNS lookup timed out after ${timeoutMs}ms`));
+						reject(new DNSTimeoutError());
 					}, timeoutMs);
 				});
 

package/src/cmd/cloud/env/delete.ts

@@ -22,7 +22,10 @@ export const deleteSubcommand = createSubcommand({
 	description: 'Delete an environment variable',
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-project'],
 	idempotent: true,
-	examples: [getCommand('env delete OLD_FEATURE_FLAG'), getCommand('env rm PORT')],
+	examples: [
+		{ command: getCommand('env delete OLD_FEATURE_FLAG'), description: 'Delete item' },
+		{ command: getCommand('env rm PORT'), description: 'Delete item' },
+	],
 	requires: { auth: true, project: true, apiClient: true },
 	schema: {
 		args: z.object({

package/src/cmd/cloud/env/get.ts

@@ -2,7 +2,6 @@ import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectGet } from '@agentuity/server';
-import { maskSecret } from '../../../env-util';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
 
@@ -15,7 +14,10 @@ export const getSubcommand = createSubcommand({
 	name: 'get',
 	description: 'Get an environment variable value',
 	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
-	examples: [getCommand('env get NODE_ENV'), getCommand('env get LOG_LEVEL')],
+	examples: [
+		{ command: getCommand('env get NODE_ENV'), description: 'Get item details' },
+		{ command: getCommand('env get LOG_LEVEL'), description: 'Get item details' },
+	],
 	requires: { auth: true, project: true, apiClient: true },
 	schema: {
 		args: z.object({
@@ -50,13 +52,13 @@ export const getSubcommand = createSubcommand({
 			// Display the value, masked if requested
 			if (process.stdout.isTTY) {
 				if (opts?.mask) {
-					tui.success(`${args.key}=${maskSecret(value)}`);
+					tui.success(`${args.key}=${tui.maskSecret(value)}`);
 				} else {
 					tui.success(`${args.key}=${value}`);
 				}
 			} else {
 				if (opts?.mask) {
-					console.log(`${args.key}=${maskSecret(value)}`);
+					console.log(`${args.key}=${tui.maskSecret(value)}`);
 				} else {
 					console.log(`${args.key}=${value}`);
 				}

package/src/cmd/cloud/env/import.ts

@@ -32,6 +32,16 @@ export const importSubcommand = createSubcommand({
 		'requires-auth',
 		'requires-project',
 	],
+	examples: [
+		{
+			command: getCommand('cloud env import .env'),
+			description: 'Import environment variables from .env file',
+		},
+		{
+			command: getCommand('cloud env import .env.local'),
+			description: 'Import from .env.local file',
+		},
+	],
 	idempotent: false,
 	requires: { auth: true, project: true, apiClient: true },
 	schema: {

package/src/cmd/cloud/env/index.ts

@@ -6,11 +6,19 @@ import { getSubcommand } from './get';
 import { deleteSubcommand } from './delete';
 import { importSubcommand } from './import';
 import { listSubcommand } from './list';
+import { getCommand } from '../../../command-prefix';
 
 export const command = createCommand({
 	name: 'env',
 	description: 'Manage environment variables for your project',
 	tags: ['fast', 'requires-auth', 'requires-project'],
+	examples: [
+		{ command: getCommand('cloud env list'), description: 'List environment variables' },
+		{
+			command: getCommand('cloud env set NODE_ENV production'),
+			description: 'Set environment variable',
+		},
+	],
 	subcommands: [
 		listSubcommand,
 		pullSubcommand,

package/src/cmd/cloud/env/list.ts

@@ -2,7 +2,6 @@ import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectGet } from '@agentuity/server';
-import { maskSecret } from '../../../env-util';
 import { getCommand } from '../../../command-prefix';
 
 const EnvListResponseSchema = z.record(
@@ -15,7 +14,10 @@ export const listSubcommand = createSubcommand({
 	aliases: ['ls'],
 	description: 'List all environment variables',
 	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
-	examples: [getCommand('env list'), getCommand('env list --mask')],
+	examples: [
+		{ command: getCommand('env list'), description: 'List items' },
+		{ command: getCommand('env list --mask'), description: 'Use mask option' },
+	],
 	requires: { auth: true, project: true, apiClient: true },
 	idempotent: true,
 	schema: {
@@ -55,7 +57,7 @@ export const listSubcommand = createSubcommand({
 				const shouldMask = opts?.mask === true;
 				for (const key of sortedKeys) {
 					const value = env[key];
-					const displayValue = shouldMask ? maskSecret(value) : value;
+					const displayValue = shouldMask ? tui.maskSecret(value) : value;
 					if (process.stdout.isTTY) {
 						console.log(`${tui.bold(key)}=${displayValue}`);
 					} else {

package/src/cmd/cloud/env/pull.ts

@@ -24,7 +24,10 @@ export const pullSubcommand = createSubcommand({
 	description: 'Pull environment variables from cloud to local .env.production file',
 	tags: ['slow', 'requires-auth', 'requires-project'],
 	idempotent: true,
-	examples: [getCommand('env pull'), getCommand('env pull --force')],
+	examples: [
+		{ command: getCommand('env pull'), description: 'Run pull command' },
+		{ command: getCommand('env pull --force'), description: 'Use force option' },
+	],
 	requires: { auth: true, project: true, apiClient: true },
 	prerequisites: ['cloud deploy'],
 	schema: {

package/src/cmd/cloud/env/push.ts

@@ -23,7 +23,7 @@ export const pushSubcommand = createSubcommand({
 		'requires-project',
 	],
 	idempotent: true,
-	examples: [getCommand('env push')],
+	examples: [{ command: getCommand('env push'), description: 'Run push command' }],
 	requires: { auth: true, project: true, apiClient: true },
 	prerequisites: ['env set'],
 	schema: {

package/src/cmd/cloud/env/set.ts

@@ -24,9 +24,9 @@ export const setSubcommand = createSubcommand({
 	idempotent: true,
 	requires: { auth: true, project: true, apiClient: true },
 	examples: [
-		getCommand('env set NODE_ENV production'),
-		getCommand('env set PORT 3000'),
-		getCommand('env set LOG_LEVEL debug'),
+		{ command: getCommand('env set NODE_ENV production'), description: 'Run production command' },
+		{ command: getCommand('env set PORT 3000'), description: 'Run 3000 command' },
+		{ command: getCommand('env set LOG_LEVEL debug'), description: 'Run debug command' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/index.ts

@@ -1,6 +1,7 @@
 import { createCommand } from '../../types';
 import { deploySubcommand } from './deploy';
-import { resourceSubcommand } from './resource';
+import { dbCommand } from './db';
+import { storageCommand } from './storage';
 import { sessionCommand } from './session';
 import { sshSubcommand } from './ssh';
 import { scpSubcommand } from './scp';
@@ -13,11 +14,16 @@ import secretCommand from './secret';
 import apikeyCommand from './apikey';
 import streamCommand from './stream';
 import vectorCommand from './vector';
+import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
 	name: 'cloud',
 	description: 'Cloud related commands',
 	tags: ['slow', 'requires-auth'],
+	examples: [
+		{ command: getCommand('cloud deploy'), description: 'Deploy your agent to the cloud' },
+		{ command: getCommand('cloud deployment list'), description: 'List all deployments' },
+	],
 	subcommands: [
 		apikeyCommand,
 		keyvalueCommand,
@@ -28,7 +34,8 @@ export const command = createCommand({
 		envCommand,
 		secretCommand,
 		deploySubcommand,
-		resourceSubcommand,
+		dbCommand,
+		storageCommand,
 		sessionCommand,
 		sshSubcommand,
 		scpSubcommand,

package/src/cmd/cloud/keyvalue/create-namespace.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 export const createNamespaceSubcommand = createCommand({
 	name: 'create-namespace',
 	aliases: ['create'],
@@ -12,9 +11,15 @@ export const createNamespaceSubcommand = createCommand({
 	idempotent: false,
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('kv create-namespace production')} - Create production namespace`,
-		`${getCommand('kv create staging')} - Create staging namespace (using alias)`,
-		`${getCommand('kv create cache')} - Create cache namespace`,
+		{
+			command: getCommand('kv create-namespace production'),
+			description: 'Create production namespace',
+		},
+		{
+			command: getCommand('kv create staging'),
+			description: 'Create staging namespace (using alias)',
+		},
+		{ command: getCommand('kv create cache'), description: 'Create cache namespace' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/delete-namespace.ts

@@ -4,7 +4,6 @@ import { ErrorCode } from '../../../errors';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 export const deleteNamespaceSubcommand = createCommand({
 	name: 'delete-namespace',
 	aliases: ['rm-namespace'],
@@ -13,9 +12,18 @@ export const deleteNamespaceSubcommand = createCommand({
 	idempotent: true,
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('kv delete-namespace staging')} - Delete staging namespace (interactive)`,
-		`${getCommand('kv rm-namespace cache --confirm')} - Delete cache without confirmation`,
-		`${getCommand('kv delete-namespace production --confirm')} - Force delete production`,
+		{
+			command: getCommand('kv delete-namespace staging'),
+			description: 'Delete staging namespace (interactive)',
+		},
+		{
+			command: getCommand('kv rm-namespace cache --confirm'),
+			description: 'Delete cache without confirmation',
+		},
+		{
+			command: getCommand('kv delete-namespace production --confirm'),
+			description: 'Force delete production',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/delete.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const KVDeleteResponseSchema = z.object({
 	success: z.boolean().describe('Whether the operation succeeded'),
 	namespace: z.string().describe('Namespace name'),
@@ -19,9 +18,12 @@ export const deleteSubcommand = createCommand({
 	idempotent: true,
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('kv delete production user:123')} - Delete user data`,
-		`${getCommand('kv delete cache session:abc')} - Delete cached session`,
-		`${getCommand('kv rm staging cache:homepage')} - Delete homepage cache (using alias)`,
+		{ command: getCommand('kv delete production user:123'), description: 'Delete user data' },
+		{ command: getCommand('kv delete cache session:abc'), description: 'Delete cached session' },
+		{
+			command: getCommand('kv rm staging cache:homepage'),
+			description: 'Delete homepage cache (using alias)',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/get.ts

@@ -4,7 +4,6 @@ import * as tui from '../../../tui';
 import { tryParseJSON } from '../../../json';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const KVGetResponseSchema = z.object({
 	exists: z.boolean().describe('Whether the key exists'),
 	data: z.union([z.string(), z.any()]).optional().describe('Value data (string or binary)'),
@@ -17,9 +16,9 @@ export const getSubcommand = createCommand({
 	tags: ['read-only', 'fast', 'requires-auth'],
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('kv get production user:123')} - Get user data`,
-		`${getCommand('kv get cache session:abc')} - Get cached session`,
-		`${getCommand('kv get staging cache:homepage')} - Get homepage cache`,
+		{ command: getCommand('kv get production user:123'), description: 'Get user data' },
+		{ command: getCommand('kv get cache session:abc'), description: 'Get cached session' },
+		{ command: getCommand('kv get staging cache:homepage'), description: 'Get homepage cache' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/index.ts

@@ -9,12 +9,20 @@ import { replSubcommand } from './repl';
 import { searchSubcommand } from './search';
 import { setSubcommand } from './set';
 import { statsSubcommand } from './stats';
+import { getCommand } from '../../../command-prefix';
 
 export const command = createCommand({
 	name: 'keyvalue',
 	aliases: ['kv'],
 	description: 'Manage keyvalue storage for your projects',
 	tags: ['read-only', 'fast', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud keyvalue repl'),
+			description: 'Start interactive key-value REPL',
+		},
+		{ command: getCommand('cloud kv get mykey'), description: 'Get value for key' },
+	],
 	subcommands: [
 		replSubcommand,
 		getSubcommand,

package/src/cmd/cloud/keyvalue/keys.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const KVKeysResponseSchema = z.object({
 	namespace: z.string().describe('Namespace name'),
 	keys: z.array(z.string()).describe('List of keys in the namespace'),
@@ -17,9 +16,9 @@ export const keysSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		`${getCommand('kv keys production')} - List all keys in production`,
-		`${getCommand('kv ls cache')} - List all cached keys (using alias)`,
-		`${getCommand('kv list staging')} - List all staging keys`,
+		{ command: getCommand('kv keys production'), description: 'List all keys in production' },
+		{ command: getCommand('kv ls cache'), description: 'List all cached keys (using alias)' },
+		{ command: getCommand('kv list staging'), description: 'List all staging keys' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/list-namespaces.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const NamespaceListResponseSchema = z.array(z.string().describe('Namespace name'));
 
 export const listNamespacesSubcommand = createCommand({
@@ -13,9 +12,9 @@ export const listNamespacesSubcommand = createCommand({
 	tags: ['read-only', 'fast', 'requires-auth'],
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('kv list-namespaces')} - List all namespaces`,
-		`${getCommand('kv namespaces')} - List namespaces (using alias)`,
-		`${getCommand('kv ns')} - List namespaces (short alias)`,
+		{ command: getCommand('kv list-namespaces'), description: 'List all namespaces' },
+		{ command: getCommand('kv namespaces'), description: 'List namespaces (using alias)' },
+		{ command: getCommand('kv ns'), description: 'List namespaces (short alias)' },
 	],
 	schema: {
 		response: NamespaceListResponseSchema,

package/src/cmd/cloud/keyvalue/repl.ts

@@ -6,14 +6,13 @@ import * as tui from '../../../tui';
 import { isPossiblyJSON, tryParseJSON } from '../../../json';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 export const replSubcommand = createCommand({
 	name: 'repl',
 	description: 'Start an interactive repl for working with keyvalue database',
 	tags: ['slow', 'requires-auth'],
 	idempotent: false,
 	requires: { auth: true, project: true },
-	examples: [`${getCommand('kv repl')} - Start interactive KV session`],
+	examples: [{ command: getCommand('kv repl'), description: 'Start interactive KV session' }],
 
 	async handler(ctx) {
 		showBanner(undefined, true);

package/src/cmd/cloud/keyvalue/search.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const KVSearchResponseSchema = z.object({
 	namespace: z.string().describe('Namespace name'),
 	keyword: z.string().describe('Search keyword used'),
@@ -24,9 +23,15 @@ export const searchSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		`${getCommand('kv search production user')} - Find all user-related keys`,
-		`${getCommand('kv search cache session')} - Find all session keys in cache`,
-		`${getCommand('kv search staging config')} - Find all config keys`,
+		{
+			command: getCommand('kv search production user'),
+			description: 'Find all user-related keys',
+		},
+		{
+			command: getCommand('kv search cache session'),
+			description: 'Find all session keys in cache',
+		},
+		{ command: getCommand('kv search staging config'), description: 'Find all config keys' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/set.ts

@@ -4,7 +4,6 @@ import * as tui from '../../../tui';
 import { isPossiblyJSON } from '../../../json';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const KVSetResponseSchema = z.object({
 	success: z.boolean().describe('Whether the operation succeeded'),
 	namespace: z.string().describe('Namespace name'),
@@ -22,9 +21,20 @@ export const setSubcommand = createCommand({
 	idempotent: true,
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('kv set production user:123 \'{"name":"Alice","email":"alice@example.com"}\'')} - Store user data`,
-		`${getCommand('kv set cache session:abc "session-data-here" --ttl 3600')} - Store session with 1h TTL`,
-		`${getCommand('kv set staging cache:homepage "<!DOCTYPE html>..." --ttl 600')} - Cache homepage for 10m`,
+		{
+			command: getCommand(
+				'kv set production user:123 \'{"name":"Alice","email":"alice@example.com"}\''
+			),
+			description: 'Store user data',
+		},
+		{
+			command: getCommand('kv set cache session:abc "session-data-here" --ttl 3600'),
+			description: 'Store session with 1h TTL',
+		},
+		{
+			command: getCommand('kv set staging cache:homepage "<!DOCTYPE html>..." --ttl 600'),
+			description: 'Cache homepage for 10m',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/stats.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const KVStatsResponseSchema = z.union([
 	z.object({
 		namespace: z.string().describe('Namespace name'),
@@ -30,9 +29,12 @@ export const statsSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		`${getCommand('kv stats')} - Show stats for all namespaces`,
-		`${getCommand('kv stats production')} - Show stats for production namespace`,
-		`${getCommand('kv stats cache')} - Show stats for cache namespace`,
+		{ command: getCommand('kv stats'), description: 'Show stats for all namespaces' },
+		{
+			command: getCommand('kv stats production'),
+			description: 'Show stats for production namespace',
+		},
+		{ command: getCommand('kv stats cache'), description: 'Show stats for cache namespace' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/objectstore/delete-bucket.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 export const deleteBucketSubcommand = createCommand({
 	name: 'delete-bucket',
 	description: 'Delete an object storage bucket and all its contents',
@@ -11,8 +10,14 @@ export const deleteBucketSubcommand = createCommand({
 	idempotent: true,
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('objectstore delete-bucket temp')} - Delete temp bucket (interactive)`,
-		`${getCommand('objectstore delete-bucket old-uploads --confirm')} - Force delete without confirmation`,
+		{
+			command: getCommand('objectstore delete-bucket temp'),
+			description: 'Delete temp bucket (interactive)',
+		},
+		{
+			command: getCommand('objectstore delete-bucket old-uploads --confirm'),
+			description: 'Force delete without confirmation',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/objectstore/delete.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const ObjectStoreDeleteResponseSchema = z.object({
 	success: z.boolean().describe('Whether the operation succeeded'),
 	bucket: z.string().describe('Bucket name'),
@@ -22,9 +21,18 @@ export const deleteSubcommand = createCommand({
 	idempotent: true,
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('objectstore delete uploads images/old-logo.png')} - Delete old logo`,
-		`${getCommand('objectstore rm assets data/temp.json')} - Remove temp file (using alias)`,
-		`${getCommand('objectstore delete backups db-2023.sql')} - Delete old backup`,
+		{
+			command: getCommand('objectstore delete uploads images/old-logo.png'),
+			description: 'Delete old logo',
+		},
+		{
+			command: getCommand('objectstore rm assets data/temp.json'),
+			description: 'Remove temp file (using alias)',
+		},
+		{
+			command: getCommand('objectstore delete backups db-2023.sql'),
+			description: 'Delete old backup',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/objectstore/get.ts

@@ -4,7 +4,6 @@ import * as tui from '../../../tui';
 import { tryParseJSON } from '../../../json';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const ObjectGetResponseSchema = z.object({
 	exists: z.boolean().describe('Whether the object exists'),
 	data: z.any().optional().describe('Object data (binary)'),
@@ -17,9 +16,18 @@ export const getSubcommand = createCommand({
 	tags: ['read-only', 'slow', 'requires-auth'],
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('objectstore get uploads images/logo.png')} - Download logo image`,
-		`${getCommand('objectstore get assets data/export.json')} - Get JSON export`,
-		`${getCommand('objectstore get backups db-2024.sql')} - Get database backup`,
+		{
+			command: getCommand('objectstore get uploads images/logo.png'),
+			description: 'Download logo image',
+		},
+		{
+			command: getCommand('objectstore get assets data/export.json'),
+			description: 'Get JSON export',
+		},
+		{
+			command: getCommand('objectstore get backups db-2024.sql'),
+			description: 'Get database backup',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/objectstore/index.ts

@@ -7,12 +7,20 @@ import { listKeysSubcommand } from './list-keys';
 import { putSubcommand } from './put';
 import { replSubcommand } from './repl';
 import { urlSubcommand } from './url';
+import { getCommand } from '../../../command-prefix';
 
 export const command = createCommand({
 	name: 'objectstore',
 	aliases: ['object', 'obj'],
 	description: 'Manage object storage for your projects',
 	tags: ['read-only', 'fast', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud objectstore repl'),
+			description: 'Start interactive object store REPL',
+		},
+		{ command: getCommand('cloud objectstore list-buckets'), description: 'List all buckets' },
+	],
 	subcommands: [
 		replSubcommand,
 		getSubcommand,

package/src/cmd/cloud/objectstore/list-buckets.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const BucketListResponseSchema = z.array(
 	z.object({
 		name: z.string().describe('Bucket name'),
@@ -21,7 +20,12 @@ export const listBucketsSubcommand = createCommand({
 		response: BucketListResponseSchema,
 	},
 	idempotent: true,
-	examples: [`${getCommand('objectstore list-buckets')} - List all buckets with stats`],
+	examples: [
+		{
+			command: getCommand('objectstore list-buckets'),
+			description: 'List all buckets with stats',
+		},
+	],
 
 	async handler(ctx) {
 		const { options } = ctx;