config set

무엇을 하는 명령인가

config set은 저장소 인식형 config loader/writer를 사용해 .ragit/config.toml의 한 개 키를 업데이트합니다.

언제 쓰는가 / 언제 쓰지 않는가

언제 쓰는가

• output, ingest, storage, embedding 설정을 바꾸고 싶을 때
• TOML을 직접 열지 않고 스크립트 가능한 방식으로 설정을 바꾸고 싶을 때

언제 쓰지 않는가

• 현재 값을 확인만 하고 싶을 때. status를 사용하십시오.
• 기본 구조와 기본값을 먼저 만들고 싶을 때. init을 사용하십시오.

기본 구문

pnpm ragit config set <key> <value> [--cwd <path>]

인자와 옵션

• <key>: 업데이트할 dotted config key입니다.
• <value>: 저장할 값입니다.
• --cwd <path>: 다른 저장소를 대상으로 실행합니다.

입력/출력 계약

• 입력은 positional 인자만 사용합니다.
• 출력은 단순 stdout 확인 메시지입니다. 현재 이 명령은 JSON envelope를 제공하지 않습니다.

대표 사용 예시

사람용 터미널 예시:

pnpm ragit config set output.format markdown

에이전트 호출 예시:

pnpm ragit config set ingest.supported_types '["adr","spec"]'

Embedding Provider 설정

RAGit은 정확히 다음 provider/model profile을 인식합니다.

인식된다는 사실만으로 evidence-backed 또는 production-supported가 되지는 않습니다. 결정적인 local-placeholder/placeholder-v1 profile은 64 dimensions이며 offline development/regression 전용입니다. 이 profile의 benchmark report는 developmentOnly: true이므로 production-quality evidence가 아닙니다.

이번 릴리스에서 production-supported인 profile은 loopback Ollama nomic-embed-text뿐입니다. OpenAI profile은 인식되고 mock contract로 검증되지만, 승인된 live evidence가 없는 opt-in integration target이며 이번 릴리스의 production support 대상이 아닙니다.

OpenAI를 사용할 때는 ingest 또는 migration 전에 명령 환경에 OPENAI_API_KEY가 있어야 합니다. 이 값은 environment-only입니다. RAGit에는 API key config key나 CLI argument가 없으며, 자격증명은 commit하거나 persist하면 안 됩니다. 초기 OpenAI target은 다음과 같이 설정합니다.

pnpm ragit config set embedding.provider openai
pnpm ragit config set embedding.model text-embedding-3-small

자격증명이 없는 기본 OpenAI provider root는 https://api.openai.com이며 RAGit이 /v1/embeddings를 붙입니다. 호환되는 custom gateway는 embedding.base_url로 설정할 수 있지만, 이 값은 최종 embeddings endpoint가 아니라 provider root입니다. username, password, query, fragment가 없는 절대 http 또는 https URL이어야 하며 trailing slash는 정규화되어 제거됩니다. embedding.base_url에 자격증명을 넣지 마십시오.

loopback Ollama를 사용할 때는 먼저 정확한 model을 로컬에서 준비합니다.

ollama pull nomic-embed-text
pnpm ragit config set embedding.provider ollama
pnpm ragit config set embedding.model nomic-embed-text
pnpm ragit config set embedding.base_url http://127.0.0.1:11434

Ollama에서는 RAGit이 /api/embed를 붙입니다. localhost, 127.0.0.1, ::1 root만 ollama-local로 보고되며 loopback이 아닌 root는 모두 custom으로 보고됩니다.

실패/주의 사항

• 잘못된 key나 잘못된 value는 config 쓰기 전에 실패합니다.
• real provider에서는 embedding.provider, embedding.model, embedding.base_url, embedding.timeout_ms, embedding.cache_enabled, embedding.cache_dir를 공식 조절면으로 보십시오. embedding.dimensions와 embedding.version은 local-placeholder에만 의미가 남아 있는 레거시 필드입니다.
• target embedding provider를 바꿔도 persisted store contract는 자동으로 바뀌지 않습니다. status에서 embedding.needsMigration=true가 보이면 이어서 migrate embeddings를 실행하십시오.
• 요청한 provider가 local-placeholder로 조용히 fallback되지는 않습니다. provider 또는 model을 바꾼 뒤에는 status를 확인하고 migration preview/apply 흐름을 따르십시오.
• embedding.cache_dir는 반드시 저장소 루트 내부를 가리켜야 합니다. 저장소 밖을 가리키면 cache 쓰기가 비활성화되고 doctor가 invalid config로 보고합니다.
• 출력이 텍스트뿐이므로, 에이전트는 후속으로 status로 상태를 검증하는 편이 좋습니다.

관련 명령

• status
• doctor
• migrate embeddings
• init